Skip to main content
superserve deploy agent.py        # Python
superserve deploy agent.ts        # TypeScript
If your agent works locally, it works on Superserve. Deploy with a single command - Superserve handles the infra.

​
Supported languages

LanguageExtensionsRuntime
Python.pyPython 3.12
TypeScript.ts, .tsxNode.js 20 via tsx
JavaScript.js, .jsx, .mjs, .cjsNode.js 20

​
How it works

Your agent reads input and writes output. Superserve handles sessions, streaming, and sandbox lifecycle.

​
Stdio mode (default)

Scripts that read from stdin and write to stdout get multi-turn conversation support automatically. Each read receives the next user message; each write streams the response back. 
while True:
    user_input = input()        # receives user message
    print(f"You said: {user_input}")  # streams response back
That’s a complete, deployable agent. The platform translates between plain stdin/stdout and the streaming API. Your code doesn’t need to know it’s running on Superserve.
Python scripts using input() / print() run in-process for lower latency. TypeScript and JavaScript agents run as subprocesses with the same protocol.

​
HTTP server mode

If your agent runs its own HTTP server (FastAPI, Express, etc.), pass --port: 
superserve deploy server.py --port 8000
Superserve proxies requests to localhost:PORT/run inside the sandbox. Use this for custom endpoints, WebSocket connections, or when your agent serves a frontend alongside the API. 
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class RunRequest(BaseModel):
    prompt: str

@app.post("/run")
async def run(req: RunRequest):
    return {"response": f"You said: {req.prompt}"}

​
Dependency detection

Superserve auto-detects and installs dependencies from your project files. No build step required.
FileLanguageWhat happens
requirements.txtPythonInstalled with uv pip install
pyproject.tomlPythonInstalled with uv pip install
package.jsonTypeScript / JSInstalled with npm install
Dependencies are installed once and cached. Subsequent deploys with the same dependencies skip the install step.
Only files at the project root are detected. Nested dependency files are ignored.

​
Project structure

Superserve packages your entire project directory (minus ignored files) and extracts it into /workspace inside the sandbox. Your entrypoint runs from there. 
research-agent/
├── research_agent/
│   ├── agent.py
│   ├── prompts/
│   └── utils/
├── .env.example
└── pyproject.toml
All files are available at runtime. Relative imports and file reads work exactly as they do locally.

​
Ignoring files

By default, common directories like .git, node_modules, .venv, and __pycache__ are excluded from the upload. To customize, create a superserve.yaml:
superserve.yaml
name: my-agent
ignore:
  - .venv
  - __pycache__
  - "*.pyc"
  - data/large-file.bin

​
Configuration file (optional)

You don’t need a config file. But if you want to customize the agent name, declare required secrets, or set ignore patterns, create a superserve.yaml:
superserve.yaml
name: my-agent
command: python agent.py

secrets:
  - ANTHROPIC_API_KEY
  - DATABASE_URL

ignore:
  - .venv
  - __pycache__
  - node_modules
FieldDescription
nameAgent name (default: directory name). Lowercase, alphanumeric, and hyphens only.
commandHow to start the agent. Auto-detected from entrypoint if omitted.
secretsEnvironment variables the agent requires. Shown as a reminder after deploy.
ignoreFiles/directories to exclude from the upload.
Run superserve init to generate a superserve.yaml with sensible defaults. If you have a .env.example, secrets are auto-detected from it.

​
What happens when you deploy

  1. Sandbox: Your agent runs in an isolated VM with its own kernel, filesystem, and network. Nothing it does can touch your infrastructure or leak into another session.
  2. Dependencies: requirements.txt, pyproject.toml, or package.json are detected and installed automatically. Cached across deploys.
  3. Network: Outbound HTTP requests route through a managed proxy that injects API keys into outgoing requests. Your agent makes authenticated calls without ever seeing the credentials. They never appear in the LLM context, logs, or tool outputs.
  4. Persistent state: The /workspace filesystem survives across turns, restarts, and sessions. Resume a conversation days later with every file and the full history intact.
  5. Live: Your agent is ready. Run it with superserve run or call it via the SDK.
The first deploy can take up to a few minutes due to dependency installation. Redeployments with unchanged dependencies are near-instant.
See the CLI reference for the full list of deploy flags, or jump to a framework guide for a complete example.