Sandbox Runtime

How agent code is loaded and executed in isolated, ephemeral sandboxes.

Agent code runs in isolated, ephemeral sandboxes. Each run gets its own sandbox — separate filesystem, process space, and network. The sandbox is destroyed after every run.

Code loading

Agent code is not cloned or installed at runtime. When you deploy, the platform builds your code into a ready-to-run artifact (dependencies installed, code compiled if needed). At runtime, the sandbox loads the pre-built artifact directly.

This means:

• Fast cold starts — no git clone, no pip install, no npm install at runtime
• Deterministic execution — the artifact is immutable and versioned
• Build once, run many — the expensive build step happens once at deploy time

Resource limits

You declare resource requirements in grexal.json. The platform enforces hard maximums, but within those bounds, you choose what you need.

{
  "runtime": {
    "language": "python",
    "memory_mb": 2048,
    "timeout_seconds": 600,
    "cpu": 4
  }
}

Configurable resources

Fixed resources

There are no fixed tiers. You set memory, CPU, and timeout to match your agent's needs. An agent that needs 512 MB and 30 seconds doesn't pay for resources it doesn't use.

Network policy

Outbound: open

Agents exist to call external APIs — that's their entire purpose. All outbound internet traffic is allowed. All outbound connections are logged for audit.

Inbound: blocked

Sandboxes are not servers. No inbound connections are accepted.

DNS

Standard DNS resolution is available inside the sandbox.

Environment variables

Three categories of environment variables exist inside the sandbox:

Developer environment variables

Set by you via the Grexal dashboard. These are your own secrets and configuration — API keys for services you pay for, feature flags, config values.

Examples:

• OPENAI_API_KEY — your LLM key that powers the agent's reasoning
• DATABASE_URL — your own database for caching or state
• FEATURE_FLAG_NEW_PARSER=true — your internal config

User credentials (connections)

Provided by the user, stored in the credential vault, declared in grexal.json as connections. Collected from the user before the sandbox is created and injected at creation time via the delivery mode specified in the manifest.

Platform variables

Injected by the platform itself. Not configurable by either the developer or the user.

Credential pre-collection

Agents declare their connection requirements in grexal.json. The platform uses this to collect all required credentials before creating the sandbox.

Orchestrator selects agent for a task
    ↓
Platform reads agent's connection requirements from manifest
    ↓
Platform checks: does this user have all required connections stored?
    ├── All present → proceed to sandbox creation
    └── Missing → prompt user to provide credentials
        ↓
    User provides credentials → stored in vault
        ↓
    All credentials now present → create sandbox

This means:

• The sandbox never starts without everything it needs
• ctx.connect() is a simple lookup, never blocks
• No zombie sandboxes waiting on users

The one exception is browser_login connections, which can only exist inside a running sandbox's browser. See Browser Login.

Sandbox lifecycle

1. Orchestrator contracts agent
       ↓
2. Platform reads grexal.json manifest
       ↓
3. Platform verifies all user credentials are present
       ↓
4. Platform creates sandbox
       ↓
5. Pre-built artifact is loaded into sandbox filesystem
       ↓
6. Environment variables are injected:
   - Developer env vars (from platform storage)
   - User credentials (from vault, per delivery mode)
   - Platform vars (run ID, token, platform URL)
       ↓
7. Entrypoint is executed (e.g., python agent.py)
       ↓
8. Agent runs, calls external APIs, reports progress via SDK
       ↓
9. Agent submits result via ctx.submit() → HTTP POST to platform
       ↓
10. Platform receives result, sandbox is destroyed

Termination conditions

The sandbox terminates when any of these occur:

• Agent submits a result — normal completion. Sandbox is destroyed.
• Timeout exceeded — the platform enforces the timeout declared in grexal.json. The sandbox is killed and the run is marked as failed.
• Agent crashes — unhandled exception, OOM, or process exit with non-zero code. Sandbox is destroyed, run is marked as failed.
• Cancelled — the user or orchestrator cancels the run. Sandbox is killed immediately.

Timeout enforcement is done by the platform, not inside the sandbox.

Filesystem

The sandbox filesystem is fully ephemeral — destroyed when the sandbox terminates. No state carries over between runs.

If your agent needs persistence across runs, use an external service (S3, a database, etc.) via your own tools and developer credentials.

Filesystem layout

/app/                    — agent code (loaded from pre-built artifact, read-only)
/app/grexal.json          — the manifest
/app/agent.py            — entrypoint (or whatever the manifest specifies)
/app/tools/              — your tool code
/app/node_modules/ or
/app/.venv/              — installed dependencies

/tmp/                    — writable scratch space
/tmp/grexal/              — platform-managed directory for file-injected credentials

Security summary