Skip to main content
POST
/
v0
/
agents
Launch an agent
curl --request POST \
  --url https://cloud.firebender.com/v0/agents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "prompt": {
    "text": "Add a README.md file with installation instructions",
    "images": [
      {
        "data": "iVBORw0KGgoAAAANSUhEUgAA...",
        "dimension": {
          "width": 2,
          "height": 2
        }
      }
    ]
  },
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "model": "claude-sonnet-4-5-20250929",
  "mode": "write",
  "skipGradleSync": false,
  "target": {
    "autoCreatePr": false,
    "branchName": "feature/add-readme"
  },
  "webhook": {
    "url": "https://example.com/webhooks/firebender-agent",
    "secret": "your-webhook-secret-key-minimum-32-characters"
  }
}
'
{
  "id": "fb_abc123xyz789",
  "name": "Add README Documentation",
  "status": "CREATING",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "branchName": "firebender/abc123xyz789",
    "url": "https://preview-sandbox-id.pit-1.try-eu.daytona.app/vnc.html",
    "prUrl": "https://github.com/your-org/your-repo/pull/1234",
    "autoCreatePr": false
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "summary": "Added README.md with installation instructions and usage examples",
  "vncUrl": "https://preview-sandbox-id.pit-1.try-eu.daytona.app/vnc.html",
  "vncToken": "eyJhbGciOiJIUzI1NiIs...",
  "recordingUrl": "https://cloud.firebender.com/v1/recordings/fb_abc123xyz789",
  "traceUrl": "https://cloud.firebender.com/v1/traces/fb_abc123xyz789"
}

Authorizations

​
X-API-Key
string
header
required

API key from Firebender Dashboard

Body

application/json
​
prompt
object
required
​
source
object
required
​
model
string
default:claude-sonnet-4-5-20250929

The LLM to use. Defaults to claude-sonnet-4-5-20250929. Use the model identifier from the Models page or the List Models endpoint.

Minimum string length: 1
Example:

"claude-sonnet-4-5-20250929"

​
mode
string

Agent mode that controls the sandbox environment capabilities:

  • write (default): Standard coding agent that reads and writes code
  • read: The agent can read and analyze code but does not make changes
  • mobile_use: write mode with a remote Android emulator. The agent can interact with and test the running app. Records and uploads the emulator screen.
  • debug_auto: Like mobile_use, but the agent will also set breakpoints, test hypotheses, and use the emulator to fix bugs. Best for automated debugging workflows.
Example:

"write"

​
skipGradleSync
boolean
default:false

Skip waiting for Gradle sync to complete before starting the agent. When true, the agent starts immediately after Android Studio launches without waiting for project indexing and Gradle sync to finish. Useful for repositories with pre-built caches or when faster startup is preferred over a fully synced project.

​
target
object
​
webhook
object

Response

Agent created successfully

​
id
string
required

Unique identifier for the cloud agent

Example:

"fb_abc123xyz789"

​
name
string
required

Name for the agent (derived from prompt)

Example:

"Add README Documentation"

​
status
enum<string>
required

Current status of the cloud agent:

  • CREATING: Sandbox is being provisioned — cloning repo, installing JDK, running setup scripts
  • SETUP: Android Studio and the Firebender plugin have launched. The project is running Gradle sync and indexing. VNC preview is available.
  • RUNNING: Agent is actively working on the task
  • FINISHED: Agent completed successfully (also set when an agent is stopped)
  • ERROR: Agent encountered an error
  • EXPIRED: Agent timed out
Available options:
CREATING,
SETUP,
RUNNING,
FINISHED,
ERROR,
EXPIRED
​
source
object
required
​
target
object
required
​
createdAt
string<date-time>
required

When the agent was created

Example:

"2024-01-15T10:30:00Z"

​
summary
string

Summary of the agent's work (available after completion)

Example:

"Added README.md with installation instructions and usage examples"

​
vncUrl
string

Direct VNC URL for the agent's live preview (only present on GET agent by ID, while agent is active)

Example:

"https://preview-sandbox-id.pit-1.try-eu.daytona.app/vnc.html"

​
vncToken
string

Authentication token for the VNC session (only present on GET agent by ID, while agent is active)

Example:

"eyJhbGciOiJIUzI1NiIs..."

​
recordingUrl
string<uri>

URL to the emulator screen recording. Available for mobile_use and debug_auto agents after completion. Returns a redirect to a time-limited presigned URL for the video file.

Example:

"https://cloud.firebender.com/v1/recordings/fb_abc123xyz789"

​
traceUrl
string<uri>

URL to the agent execution trace. Enterprise only. Available after agent completion.

Example:

"https://cloud.firebender.com/v1/traces/fb_abc123xyz789"