Skip to main content

What You’ll Learn

  • How to start a long-running server process as a background subprocess inside the sandbox
  • How to use urllib from inside the sandbox to exercise the server’s API
  • How to poll for server readiness before running tests
  • How to verify process cleanup after the server stops

Prerequisites

  • Declaw running locally or in the cloud (see Deployment)
  • DECLAW_API_KEY and DECLAW_DOMAIN set in your environment
This example is available in Python. TypeScript support coming soon.

Code Walkthrough

1. Define the server

The server uses only Python’s stdlib http.server and json modules — no pip installs needed:

2. Define the client script

The client starts the server as a subprocess, waits for readiness, exercises the API, then shuts down:

3. Upload and run from the orchestrator

The outer Python script uploads both files and runs the client (which manages the server internally):

Expected Output

Adapting for MCP

This pattern directly applies to Model Context Protocol (MCP) servers. An MCP server is an HTTP or stdio API that exposes tools to an LLM agent. Running it inside a Declaw sandbox means:
  • The MCP server’s filesystem access is isolated from the host
  • Network egress from the MCP server can be restricted to a specific allowlist
  • PII in the MCP server’s HTTP responses can be redacted before reaching the agent
The supported way to talk to an MCP server running inside a sandbox is stdio over the sandbox’s command/PTY APIs: start the server with sbx.commands.run("your-mcp-server --stdio", background=True) and drive it from an agent that proxies stdio through sbx.pty or sbx.commands.send_stdin. Per-sandbox public URLs (e.g. <port>-<id>.api.declaw.ai) are not part of the Declaw platform — path-based APIs under api.declaw.ai/sandboxes/<id>/... are the only customer-facing surface.