CLOUD AGENTS

Launch an agent

Create and launch cloud agents from the Nah Cloud dashboard. Enter a plain-English description, pick your model and sandbox, choose telemetry tier, and watch the run in real time — all without leaving the browser.

Create an agent from the dashboard

The dashboard is the fastest way to go from idea to running agent. No CLI setup required.

1. New agent

Click New Agent in the sidebar. Give it a name and paste or type a plain-English description of what you want done — code review, refactor, test generation, documentation, migration, anything.

text
Example prompts:
"Review the login flow in src/auth.ts and summarize failure cases"
"Add error handling to the payment webhook in /api/payments"
"Generate unit tests for the user service in src/services/user.ts"
"Migrate the legacy GraphQL resolvers to tRPC in /packages/api"

2. Configure the run

Set the parameters that shape how the agent works:

ModelProvider + model (e.g., anthropic:claude-sonnet-4)
Permissionsask (default) | yolo | readonly
Sandboxsmall | default | large | xlarge
TelemetryMetrics only (default) | Full traces
TTLAuto-stop after N seconds (default 1 hour)

3. Attach a repository

Select a connected GitHub/GitLab repo or enter a Git URL. The sandbox clones it read-only — agents see the working tree but cannot push.

4. Launch & watch

Hit Launch. The sandbox boots in seconds, the harness starts, and the event stream appears live in the dashboard. You see every tool call, file read, and model response as it happens.

How a cloud run works

1. Sandbox boots

A persistent Linux VM forks from a snapshot in seconds. Your repo is cloned read-only into the working tree. The sandbox stops between runs — idle time costs ~$0.

2. Harness starts

The sandbox runs our harness. The agent loop begins, streaming events over a secure channel back to the dashboard (and optionally your terminal).

3. You stay in control

Stop, inspect, or reopen the run at any time. Billing stops immediately on stop. Use prepaid Nah AI credits, or bring your own model key for the agent.

Sandbox sizing

Choose a sandbox size that fits the work. Billed per second while running; stopped sandboxes cost nothing.

SIZECPURAMDISK$/HOURBEST FOR
small2 vCPU4 GB12 GB$0.018Quick reviews, linting, tests
default4 vCPU8 GB50 GB$0.04General coding, refactors, builds
large8 vCPU16 GB125 GB$0.08Heavy compiles, monorepos, ML
xlarge16 vCPU32 GB251 GB$0.20Large-scale builds, data workloads

Select sandbox.type in the dashboard launch form or via the API.

Telemetry tiers

Telemetry is opt-in. Choose per-run or set a project default:

Tier 1 — Metrics (default)

Every run records: duration, token usage, model, step counts, tool usage, error classes. No prompt content leaves the machine.

run start/end
duration & status
input/output tokens
model & provider
step counts & tools
error class

Tier 2 — Traces (opt-in)

Enable at project level or per-run with trace: true. Prompts, assistant text, tool I/O, full error text — behind a flag, short TTL, never sold or stored long-term.

prompts
assistant text
tool inputs
tool outputs

Launch parameters reference

Dashboard form fields

Model
e.g., anthropic:claude-sonnet-4
Permissions
ask | yolo | readonly
Trace
Toggle full content tracing
Sandbox
small | default | large | xlarge
TTL (seconds)
Auto-stop after N seconds

API body

json
{
  "prompt": "Review the login flow...",
  "model": "anthropic:claude-sonnet-4",
  "permissions": "ask",
  "trace": false,
  "sandbox": { "type": "default", "ttlSeconds": 3600 }
}

After launch

Once the agent is running, you can:

  • Monitor progress in real-time via the event stream in the dashboard
  • View token usage and step counts as they accumulate
  • Stop the run at any time — billing stops immediately
  • Open the trace waterfall if tracing was enabled
  • Inspect the working tree and generated artifacts
  • Reopen a completed run to continue from where it left off
View billing & metering

Integrations

The dashboard is the primary interface, but every operation also works from the terminal and API — useful for CI, scripting, and power users who live in the shell.

Terminal workflow

Authenticate once, then launch and manage agents entirely from your shell.

bash
# One-time auth (stores token in platform credential store)
nah cloud login

# Launch from plain English
nah cloud launch "Add error handling to the payment webhook"

# Stream live events
nah cloud events <agent-id> --follow

# Interrupt a running agent
nah cloud interrupt <agent-id>

# Reopen a stopped session — full history preserved
nah cloud resume <agent-id>

# Tail working tree changes
nah cloud diff <agent-id> --follow

# Stop when done
nah cloud stop <agent-id>
Full terminal guide

Programmatic API

Launch and control agents from CI, scripts, or your own tools via the REST API.

bash
curl -X POST https://api.nah.cloud/v1/agents/launch   -H "Authorization: Bearer $NAH_CLOUD_TOKEN"   -H "Content-Type: application/json"   -d '{
    "prompt": "Run the test suite and fix failures",
    "model": "anthropic:claude-sonnet-4",
    "permissions": "yolo",
    "trace": true
  }'
API reference

Web dashboard

Real-time event stream, trace waterfall, billing, and spend ceilings. Opens automatically on launch or with nah cloud url.

  • Live run progress & step-by-step events
  • Token usage & cost breakdown per run
  • Trace waterfall (when enabled)
  • Spend ceilings & usage history

CI/CD integration

Set NAH_CLOUD_TOKEN in your CI environment to run agents as part of pipelines — code review, test generation, migration scripts.

yaml
# .github/workflows/nah-agent.yml
- name: Run Nah Cloud agent
  env:
    NAH_CLOUD_TOKEN: ${{ secrets.NAH_CLOUD_TOKEN }}
  run: |
    nah cloud launch "Review PR #${{ github.event.number }} for security issues" \
      --permissions readonly --trace

Opt-in by default

Nah Cloud never sends anything unless you explicitly log in and launch an agent. Local sessions continue to run read-only with no network traffic.
Detailed CLI reference Billing & metering Terminal integration guide Pricing calculator