# CircuitNotion Cloud

> Agent-friendly Linux VPS and container hosting, built for AI agents and the companies that ship them. Create a machine, put code on it, run it, and get a public HTTPS URL, all over one REST API or MCP server.

Base URL: https://cloud.circuitnotion.com/api/v1
MCP endpoint (Streamable HTTP): https://cloud.circuitnotion.com/mcp
OpenAPI: https://cloud.circuitnotion.com/api/v1/openapi.json
Auth: header "Authorization: Bearer cnc_..." (create keys at https://cloud.circuitnotion.com/api-keys; scopes: read, write, exec, files)
Errors: {"error": {"code": "...", "message": "...", "hint": "..."}}. Branch on "code".

## Concepts
- instance: a VPS (kind "vps", from a template: ubuntu-24.04, debian-12, alpine-3.21, python-3.12, node-22) or an app (kind "app", from a Docker image or a git repo with a Dockerfile).
- ubuntu-24.04-docker: a VPS with Docker Engine + Compose + Buildx inside (size small or larger; only where GET /templates says "available"). The Docker daemon starts before start_command, so start_command can be "cd /data/app && docker compose up". Inside, publish services with network_mode: host / --network host on $PORT: that is gVisor's supported way (-p port mapping may not work in the sandbox).
- VPS root filesystems persist across restarts. /data persists across redeploys for both kinds.
- Every instance gets https://<slug>.circuitnotion.com routed to its http_port (default 8080; $PORT is set). Bind to 0.0.0.0.
- Instances of one account share a private network and reach each other by slug (internal_hostname).
- start_command: a command the platform keeps running (restarted if it exits). Logs go to GET /instances/{id}/logs.
- Sizes: nano 0.25 vCPU/256MB, micro 0.5/512MB, small 1/1GB, medium 2/2GB, large 4/4GB, xlarge 8/8GB. Plans cap the total.
- GPUs: where the server has NVIDIA GPUs, GET /templates also lists gpu-<model>-x<count> sizes (whole GPUs or MIG slices, never shared) with "available". Use template cuda-12.8 or any image; nvidia-smi works inside. GPU instances keep their GPUs while stopped and cannot be resized. GET /instances/{id}/metrics includes per-GPU use.
- GPU waitlist: when there are no GPUs (or none free), PUT /gpu-waitlist {"gpu":"h100","gpu_count":1,"use_case":"inference","timeframe":"month","notes":"Llama 70B for a support agent"} tells the operator what you need. GET /gpu-waitlist lists the accepted values.

## Host an agent API in 4 calls
1. POST /instances?wait=true  {"name":"my-agent","template":"python-3.12","size":"small","http_port":8000}
2. PUT  /instances/my-agent/files?path=/app/main.py   (raw body = your code)   or PUT /instances/my-agent/archive?path=/app (tar.gz of a project)
3. POST /instances/my-agent/exec  {"command":"pip install fastapi uvicorn","timeout_seconds":300}
4. PATCH /instances/my-agent?wait=true {"start_command":"cd /app && uvicorn main:app --host 0.0.0.0 --port $PORT"}
Then GET /instances/my-agent returns "url": https://my-agent-xxxxx.circuitnotion.com

## Other operations
- GET /instances, GET/PATCH/DELETE /instances/{id}  ({id} may be id, slug or name)
- POST /instances/{id}/start | stop | restart | redeploy   (?wait=true)
- PATCH /instances/{id}/env {"set":{"OPENAI_API_KEY":"..."},"unset":["OLD"]}  (restarts to apply unless "apply":false)
- POST /instances/{id}/exec {"command":"ls -la /app","cwd":"/app","timeout_seconds":60} -> {exit_code, stdout, stderr}
- GET /instances/{id}/files?path=/app  (lists dirs, reads files; ?raw=true for bytes)
- GET /instances/{id}/logs?tail=200&since=10m  (?follow=true for SSE)
- GET /instances/{id}/metrics
- Deploy an image: POST /instances {"name":"api","image":"ghcr.io/acme/agent:1.0","http_port":8000,"env":{"KEY":"v"}}
- Deploy git: POST /instances {"name":"api","git":{"url":"https://github.com/acme/agent.git","ref":"main"}}  (paid plans)
- Retries: send "Idempotency-Key: <uuid>" on POST /instances.

## MCP
Claude Code: claude mcp add --transport http circuitnotion-cloud https://cloud.circuitnotion.com/mcp --header "Authorization: Bearer cnc_..."
Tools: list_templates, get_account, list_instances, get_instance, create_instance, update_instance, start_instance, stop_instance, restart_instance, redeploy_instance, delete_instance, get_env, set_env, exec_command, read_file, list_files, write_file, delete_file, get_logs, get_metrics, get_build_log, http_request.