CircuitNotion Cloud docs

Quickstart

1. Sign in with your CircuitNotion account. Every account starts on the free plan.
2. Open Instances → New instance, pick a template such as Python 3.12 or Ubuntu 24.04, and create it.
3. Open the instance's Terminal, start your server on $PORT (8080 by default), and visit its URL.

Everything in the dashboard maps one to one to the REST API and the MCP tools, so an agent can do the same steps.

Connect an agent (MCP)

The MCP server speaks Streamable HTTP at https://cloud.circuitnotion.com/mcp. Create an API key on the API keys page of the dashboard and send it as a bearer token.

claude mcp add --transport http circuitnotion-cloud https://cloud.circuitnotion.com/mcp \
  --header "Authorization: Bearer cnc_..."

{
  "mcpServers": {
    "circuitnotion-cloud": {
      "type": "http",
      "url": "https://cloud.circuitnotion.com/mcp",
      "headers": { "Authorization": "Bearer cnc_..." }
    }
  }
}

The 22 tools cover the whole lifecycle: list_templates, create_instance, exec_command, write_file, read_file, get_logs, get_metrics, http_request, start/stop/restart/redeploy/delete and environment variables.

REST API

Base URL https://cloud.circuitnotion.com/api/v1, JSON in and out. The full schema is at /api/v1/openapi.json. Long operations accept ?wait=true and return once the instance has settled.

curl -X POST "https://cloud.circuitnotion.com/api/v1/instances?wait=true" \
  -H "Authorization: Bearer $CNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","template":"python-3.12","size":"small","http_port":8000}'

Deploy an API in four calls

1. POST /instances?wait=true with a template, a size and the port your server will use.
2. PUT /instances/my-agent/files?path=/app/main.py with your code as the body, or upload a tar.gz to /archive.
3. POST /instances/my-agent/exec with {"command":"pip install fastapi uvicorn"}.
4. PATCH /instances/my-agent?wait=true with a start_command the platform keeps running.

curl -X PATCH "https://cloud.circuitnotion.com/api/v1/instances/my-agent?wait=true" \
  -H "Authorization: Bearer $CNC_API_KEY" -H "Content-Type: application/json" \
  -d '{"start_command":"cd /app && uvicorn main:app --host 0.0.0.0 --port $PORT"}'

GET /instances/my-agent then returns its url. Logs are at /instances/my-agent/logs (add ?follow=true to stream them).

Templates and sources

An instance comes from exactly one source:

• Template: a VPS whose root filesystem survives restarts. Available on this server:

• Ubuntu 24.04 LTSubuntu-24.04General purpose Linux server. apt, bash, full root inside the sandbox.
• Debian 12debian-12Minimal, stable Debian base.
• Alpine 3.21alpine-3.21Tiny musl-based Linux. Fastest to boot.
• Python 3.12 agent runtimepython-3.12Python with pip for FastAPI/LangChain/LlamaIndex style agents and tool servers.
• Node.js 22 agent runtimenode-22Node.js LTS with npm for TypeScript agents, MCP servers and APIs.
• Ubuntu 24.04 + Dockerubuntu-24.04-dockerA VPS with Docker Engine, Compose and Buildx inside: docker run, docker compose up, docker build.

• Docker image: any public image, run as an app. It is pulled again on every redeploy.
• Git repository: the repository's Dockerfile is built on every deploy (paid plans). Private repositories can embed a read-only token in the URL; it is stored encrypted.

Sizes and what each plan allows are listed on the pricing page.

URLs and networking

• Each public instance is served at https://<slug>.circuitnotion.com and routed to its HTTP port. $PORT is set to it; bind to 0.0.0.0.
• Turn the public URL off to keep an instance private.
• Your instances share a private network and reach each other by slug, for example http://my-db-x2k9q:5432.

Storage

• VPS (templates): the root filesystem persists across restarts, so installed packages stay.
• /data persists for every instance, including across redeploys. Redeploying a VPS resets everything outside /data.
• Environment variables and git URLs are encrypted at rest.

GPUs and the waitlist

Where the server has NVIDIA GPUs, GET /api/v1/templates also lists gpu-* sizes with whole GPUs or MIG slices that are never shared, and whether each is free. Use the cuda-12.8 template or any image; nvidia-smi works inside. GPU instances keep their GPUs while stopped and cannot be resized.

When there are no GPUs, or none free, join the waitlist from the dashboard or the API. Your answers tell us which GPUs to bring online first, and joining again updates your entry without losing your place.

curl -X PUT "https://cloud.circuitnotion.com/api/v1/gpu-waitlist" \
  -H "Authorization: Bearer $CNC_API_KEY" -H "Content-Type: application/json" \
  -d '{"gpu":"a100","gpu_count":2,"use_case":"fine-tuning","timeframe":"quarter"}'

GET /api/v1/gpu-waitlist returns your entry and the accepted values; DELETE takes you off the list.

API keys and scopes

Keys start with cnc_ and are shown once. Give each agent its own key with only the scopes it needs, optionally limited to one instance or with an expiry date. Keys cannot manage keys or billing.

Errors and limits

Errors are JSON: {"error": {"code": "...", "message": "...", "hint": "..."}}. Branch on code; the hint says what to do next. Requests are rate limited per key, and creating instances accepts an Idempotency-Key header so retries never create duplicates.