Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt

Use this file to discover all available pages before exploring further.

POST /sandboxes
Creates a repo-backed sandbox deployment for a branch or PR. Use this when you want to deploy your app or agent into an isolated sandbox, attach selected twins, seed those twins from a scenario, and inject environment variables into the deployed process. Request body
FieldTypeRequiredDescription
repostringYesRepository in owner/repo format.
branchstringConditionalBranch to deploy. Required unless pr_url is provided.
pr_urlstringConditionalPull request URL to deploy. Required unless branch is provided.
twinsarray<string>NoTwins to include. When omitted, Arga can use the scenario’s twins or detected runtime profile.
scenario_idstringNoSaved scenario or preset id used to seed twins.
scenario_promptstringNoNatural-language seed prompt. Used when scenario_id is omitted.
ttl_minutesintegerNoSandbox TTL, 1-480 minutes. Defaults to 60. Free-plan accounts are capped at the free-tier TTL limit; requests above the cap are rejected by plan-limit enforcement.
envobjectNoExtra environment variables to inject into the deployed app. These override generated twin env vars on key conflict.
In production, the authenticated user must have the GitHub integration connected. twins must be supported twin names from the runtime catalog; invalid names return 400. Response Queued sandboxes return empty connection details until deployment is ready: 
{
  "sandbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "app_url": null,
  "twins": {},
  "env_vars": {}
}
When ready, poll Get a sandbox to retrieve app_url, per-twin URLs, and env vars. 
{
  "sandbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "ready",
  "app_url": "https://a1b2c3d4-app.preview.argalabs.com",
  "twins": {
    "gmail": {
      "base_url": "https://a1b2c3d4-gmail.preview.argalabs.com",
      "admin_url": "https://a1b2c3d4-gmail.internal.argalabs.com",
      "env_vars": {
        "GMAIL_ACCESS_TOKEN": "ya29.gmail-twin-owner",
        "GMAIL_API_BASE_URL": "https://a1b2c3d4-gmail.preview.argalabs.com"
      }
    }
  },
  "env_vars": {
    "GMAIL_ACCESS_TOKEN": "ya29.gmail-twin-owner",
    "GMAIL_API_BASE_URL": "https://a1b2c3d4-gmail.preview.argalabs.com"
  }
}