Sandbox infrastructure
documentation.

The product boundary

Services own the work. Condensation runs the sandbox.

Condensation provides the shared infrastructure for every consuming service from the outset: sandbox lifecycle, isolation, compute, storage, networking, and access. Nanohub owns Git and repository collaboration; Codegraff owns agents and model workflows. Future services use the same boundary.

The target API is a generic sandbox resource with service attribution. Service-scoped credentials, execution, logs, resource limits, and usage metering belong on that infrastructure contract. This is the architecture direction, not a claim that those API capabilities are already shipped.

Current implementation: the endpoints below are legacy workload adapters. They still provision account, agent, and app environments. They remain documented for existing operators; the generic sandbox API is not available yet.

01 / Get connected

Your first request.

The service is available to trusted internal operators at https://sandbox.condensation.ai. Obtain an operator key from the fleet owner and set CONDENSATION_TOKEN in your local environment or secret manager.

The operator key can manage the entire fleet. Keep it out of browser code, repositories, and agent environments. There are no public sign-ups or project-scoped keys yet.

curl https://sandbox.condensation.ai/healthz \
  -H "Authorization: Bearer $CONDENSATION_TOKEN"

This read returns fleet health and inventory counts. The public API root contains product information only; every fleet endpoint requires authentication.

The client uses Python’s standard library. Set CONDENSATION_URL=https://sandbox.condensation.ai and CONDENSATION_TOKEN, or use a private local credential file at ~/.config/condensation/operator.json with url and token fields and file mode 0600.

python3 condensation.py status
python3 condensation.py list accounts
python3 condensation.py list apps

02 / Legacy Nanohub adapter

A home for the whole project.

Ensure one account environment, then use its nanohub Git service for multiple repositories. Repeating the same account name reuses its mapping. One account VM is the source of truth; sibling agents connect as clients.

curl https://sandbox.condensation.ai/v1/accounts \
  -H "Authorization: Bearer $CONDENSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account":"my-project"}'

The response includes the account key, sandbox_id, and git_url. The Git service has its own access controls: a returned URL is not a credential. The API does not disclose the Git operator token.

03 / Legacy Codegraff adapter

Give the agent its own room.

Prepare a sibling environment connected to an account repository. The repository must already exist in the account’s Git service. Use repository as a repo name or owner/repo, without the .git suffix.

{
  "account": "my-project",
  "repository": "my-repository",
  "task": "Review the failing test",
  "codegraff_key": "cg_sk_REPLACE_WITH_API_SCOPE_KEY"
}

curl https://sandbox.condensation.ai/v1/agents \
  -H "Authorization: Bearer $CONDENSATION_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @agent-request.json

Use a dedicated Codegraff key with API scope. That key enters the agent environment for model access; keep the request file private and remove it when no longer needed. Model usage is charged through that Codegraff account.

The current response reports loop: gateway_ready. Git and model access are prepared, but an agent loop does not start automatically.

04 / Legacy app adapter

Give the work an address.

The current preview starter creates a separate VM and serves a static page with Python. It returns a named HTTPS URL. Node and framework-specific templates are still planned.

curl https://sandbox.condensation.ai/v1/apps \
  -H "Authorization: Bearer $CONDENSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"hello","title":"My first preview"}'

Record the returned key to inspect or remove that specific environment. Preview names are converted to distinct hashed hostnames; creating another preview with the same name creates a separate environment.

Current Git and preview URLs use the fleet’s existing domains. Treat preview content as potentially public, and do not put secrets in a static preview.

05 / Lifecycle and cost

Clean up deliberately.

curl -X DELETE \
  https://sandbox.condensation.ai/v1/apps/REPLACE_WITH_RETURNED_KEY \
  -H "Authorization: Bearer $CONDENSATION_TOKEN"

Deletion destroys guest data. Deleting an account VM can erase its Git repositories. Keep important work backed up separately. This release does not provide automatic pause/resume or durable volume recovery.

After a timeout or an upstream error, inspect the inventory before retrying a create or delete request. The operation may already have completed. Neither the service nor the Python client automatically retries a mutation.

Usage metering and invoices are planned, not enabled. Proposed rates are published on the pricing page. The intended ledger attributes compute, storage, and network usage to the consuming service.

06 / Reference

The API at a glance.

Unknown routes and query strings are rejected. JSON request bodies are limited to 32 KiB. Authentication failures return 401; a missing service configuration returns 503; upstream failures return a sanitized error.