Documentation — OCL Nexus

Why OCL Nexus?

OCL Nexus is an "Agentic Compute Fabric". We provide the high-performance Ubuntu environments, NVMe storage, and internal networking that agents need to build and run real services. By using standard conventions like nexus-start.sh, your agents can move from "writing code" to "deploying production-ready services" autonomously.

Quick Start

Create an account & top up your wallet

Sign up at oclhosting.com. New accounts receive €5 free credits. To add more credits, visit the Wallet. Credits are consumed at €0.008 / hour per active workload.

Generate an API key

Go to Dashboard → API Keys and click Create API Key. Copy the key — it is shown only once. Keys follow the format nx_.... Never commit API keys to source control — treat them like passwords.

Connect your IDE or agent

Paste your key into the config for your tool below. Your agent can then call all 15 Nexus MCP tools to deploy sandboxes, upload code, run services, and verify they're responding.

Quick & Dirty

If you are using any modern agentic harness, you can try configuring it using a prompt. Get your API key and ask your agent something like this:

“Please read the documentation at https://oclnexus.com/docs and the agent playbook at https://oclnexus.com/docs/playbook. Set up the OCL MCP connection and create a CLAUDE.md (or equivalent) in this project using the starter template from the docs.”

Connect Your IDE

OCL Nexus exposes a Model Context Protocol server at https://app.oclhosting.com/api/mcp/v1.

Transport notes:

Clients must send Accept: application/json, text/event-stream — requests without this header will be rejected.
Responses use SSE framing (data: {...}). MCP-compliant clients handle this automatically; custom clients must parse the data: line.

Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config and add the following to your claude_desktop_config.json. Replace YOUR_API_KEY with your key from the API Keys page.

json

{
  "mcpServers": {
    "ocl-nexus": {
      "url": "https://app.oclhosting.com/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

File: claude_desktop_config.json

Verify it works: ask your agent to call nexus_list_workloads — if it returns a JSON response with a workloads array (empty or not), the MCP connection is live.

Claude Code

Add the following to ~/.claude/settings.json (global) or .claude/settings.json (per-project). Replace YOUR_API_KEY with your key from the API Keys page.

Required: the "type": "http" field is mandatory for Claude Code and silently fails without it. Claude Desktop does not need this field.

json

{
  "mcpServers": {
    "ocl-nexus": {
      "type": "http",
      "url": "https://app.oclhosting.com/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

File: ~/.claude/settings.json or .claude/settings.json

Verify it works: ask your agent to call nexus_list_workloads — if it returns a JSON response with a workloads array (empty or not), the MCP connection is live.

Add a `CLAUDE.md` to your project (recommended)

Claude Code reads CLAUDE.md at the project root on every session. This starter gives your agent the key rules without re-discovering them.

markdown

## OCL Nexus
MCP server `ocl-nexus` is available. Use it to deploy and manage cloud sandboxes.

### Key rules
- **Billing:** €0.008/hr per running workload — call `nexus_terminate` when done to stop charges
- Always call `nexus_wait_for_ready` after `nexus_deploy` or `nexus_restart` — never poll manually
- Use `nexus_write_files` for 2+ files in one call
- Use `python3` / `pip3 install --break-system-packages`, never `python` / `pip`
- Bind to the blueprint's container port: **8000** for python-sandbox, **3000** for nodejs-sandbox
- For pod-to-pod HTTP calls use port **80**: `http://svc-<id>:80` — the K8s Service translates :80 → container port internally
- `nexus_fetch` hits the public HTTPS URL, not the internal URL; use `nexus_execute_command` + `curl` to test internal reachability

### Service mode pattern (Flask)
    # nexus-start.sh
    pip3 install flask --break-system-packages --quiet && exec python3 app.py

### Workflow
deploy → wait_for_ready → write_files → restart → wait_for_ready → fetch /health

Cursor

Open Cursor → Settings → MCP, or create .cursor/mcp.json in your project root. Replace YOUR_API_KEY with your key from the API Keys page.

Security: .cursor/mcp.json lives inside your project directory and can be accidentally committed to git. Either add it to .gitignore, or use Cursor → Settings → MCP (global config) to keep your API key outside the repo.

json

{
  "mcpServers": {
    "ocl-nexus": {
      "url": "https://app.oclhosting.com/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

File: .cursor/mcp.json

Verify it works: ask your agent to call nexus_list_workloads — if it returns a JSON response with a workloads array (empty or not), the MCP connection is live.

Continue.dev

Merge the following into ~/.continue/config.json. Replace YOUR_API_KEY with your key from the API Keys page.

json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "http",
          "url": "https://app.oclhosting.com/api/mcp/v1",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    ]
  }
}

File: ~/.continue/config.json

Verify it works: ask your agent to call nexus_list_workloads — if it returns a JSON response with a workloads array (empty or not), the MCP connection is live.

Instance Endpoint Access

All instance endpoints (e.g. https://inst-xxxx.oclhosting.com) are protected by OCL authentication. Only browsers with an active OCL session can reach them — unauthenticated requests are rejected at the gateway.

Public access — shareable URLs reachable without an OCL account — is planned for a near future release.

Billing

Billing model: Prepaid credits
Hourly rate (per workload): €0.008 / hr
Monthly equivalent: ≈ €6 / month
Welcome credits: €5 (one-time, no card)

Credits are deducted hourly for each running workload. Terminate workloads when not in use to preserve balance. Monitor balance via the Wallet or the nexus://wallet/balance MCP resource.

Troubleshooting

Symptom	Likely cause	Fix
nexus_* tools not found	MCP server not loaded	Check config file path and restart your IDE. For Claude Code, confirm "type": "http" is present.
nexus_list_workloads returns auth error	Invalid or expired API key	Generate a new key in Dashboard → API Keys. Keys are shown only once.
nexus_fetch returns connection refused	Service not running or wrong port	Confirm nexus_wait_for_ready completed. Check port binding: 8000 for python-sandbox, 3000 for nodejs-sandbox.
nexus_fetch works but internal curl fails	Using public URL for pod-to-pod call	Use nexus_execute_command + curl http://svc-<id>:80 for internal connectivity tests.
Workload never becomes ready	Service crashed on startup	Check nexus_get_logs for errors. Verify nexus-start.sh is executable and exits on error (set -e).

OCL Nexus Hub

Why OCL Nexus?

Quick Start

Create an account & top up your wallet

Generate an API key

Connect your IDE or agent

Quick & Dirty

Connect Your IDE

Claude Desktop

Claude Code

Add a CLAUDE.md to your project (recommended)

Cursor

Continue.dev

Instance Endpoint Access

Billing

Troubleshooting

Add a `CLAUDE.md` to your project (recommended)