Skip to main content
Get your first agent running on Superserve in minutes. This guide walks you through installation, authentication, creating a simple agent, and deploying it to production.

​
Prerequisites

​
Install the CLI

curl -fsSL https://superserve.ai/install | sh
Verify the installation: 
superserve --version

​
Authenticate

Log in to your Superserve account: 
superserve login
This opens your browser and displays a verification code: 
To authenticate, visit: https://console.superserve.ai/device
Enter code: ABCD-1234

Browser opened automatically.

Waiting for authentication...
✓ Authenticated successfully!
You can also authenticate with an API key using superserve login --api-key YOUR_KEY. Generate API keys in the console.

​
Create Your First Agent

1

Create a project directory

mkdir my-agent
cd my-agent
2

Create your agent file

Create a file called agent.py with a simple chatbot:
"""
Minimal chatbot built with Claude Agent SDK deployed on Superserve.
"""

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, TextBlock

options = ClaudeAgentOptions(
    model="sonnet",
    system_prompt="You are a helpful assistant.",
    permission_mode="bypassPermissions",
    continue_conversation=True,
)


async def main():
    async with ClaudeSDKClient(options=options) as client:
        while True:
            try:
                user_input = input()
            except EOFError:
                break
            await client.query(prompt=user_input)
            async for msg in client.receive_response():
                for block in getattr(msg, "content", []):
                    if isinstance(block, TextBlock):
                        print(block.text)


asyncio.run(main())
3

Add dependencies

For Python agents, create a requirements.txt:
claude-agent-sdk
For TypeScript/JavaScript agents, create a package.json:
Mastra
{
  "name": "my-agent",
  "type": "module",
  "dependencies": {
    "@mastra/core": "^0.1.0"
  }
}

​
Deploy Your Agent

Deploy your agent with a single command: 
superserve deploy agent.py --name my-agent
For TypeScript agents, use superserve deploy agent.ts --name my-agent
You’ll see real-time progress as your agent is packaged, uploaded, and dependencies are installed: 
  Packaging project... ✓ (2.4 KB)
  Uploading to Superserve... ✓
  Installing dependencies... ✓ (12.3s)

  Deployed 'my-agent' in 14.8s

  Set your API keys as secrets:
  ┌─────────────────────────────────────────────────────┐
  │ superserve secrets set my-agent KEY=VALUE           │
  └─────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────┐
  │ superserve run my-agent "your prompt here"          │
  └─────────────────────────────────────────────────────┘

  Or try it in the Playground:
  https://playground.superserve.ai/agents/agt_abc123/
If you redeploy an existing agent, you’ll be prompted to confirm. Use --yes to skip confirmation.

​
Set Your Secrets

Your agent needs API keys to call AI providers. Set them as encrypted secrets: 
superserve secrets set my-agent ANTHROPIC_API_KEY=sk-ant-...
You’ll see confirmation: 
✓ Set 1 secret(s) for agent 'my-agent'
Current secrets: ANTHROPIC_API_KEY

Try your agent in Playground: https://playground.superserve.ai/agents/agt_abc123/
Secrets are encrypted at rest and injected via a credential proxy. They never appear in logs or LLM context. Learn more in Secret Management.

​
Run Your Agent

Start an interactive session with your agent: 
superserve run my-agent
The CLI starts a live session where you can chat with your agent: 
You > What is the capital of France?

Agent > The capital of France is Paris.

Completed in 1.2s

You > And what's its population?

Agent > Paris has approximately 2.1 million people in the city proper.

Completed in 0.8s

You >
Type exit or press Ctrl+C to end the session.

​
Single-shot mode

For one-off queries, pass your prompt directly: 
superserve run my-agent "What is the capital of France?"
The agent responds and exits: 
The capital of France is Paris.
Add --single to exit after the first response without entering interactive mode.

​
JSON output

For programmatic use, output raw JSON events: 
superserve run my-agent --json "Hello!"

{"type":"status","status":"running"}
{"type":"message","content":"Hello! How can I help you today?"}
{"type":"done"}

​
What’s Happening Under the Hood

When you run your agent, Superserve:
  1. Spins up an isolated microVM - Your agent runs in a dedicated Firecracker sandbox, completely isolated from other agents
  2. Mounts persistent storage - The /workspace directory persists across sessions so your agent can save and resume state
  3. Injects secrets via proxy - API keys are injected at the network level and never appear in your agent’s environment or logs
  4. Streams responses - Output streams in real-time via Server-Sent Events
All of this happens automatically with zero configuration.

​
Next Steps

Deploy a Complex Agent

Learn how to deploy agents with custom dependencies, file uploads, and advanced configuration

Manage Secrets

Set required secrets, rotate keys, and manage environment variables

Use the SDK

Integrate Superserve into your applications with the TypeScript SDK

CLI Reference

Explore all available commands and options

​
Common Issues

​
Dependencies failing to install

If your deployment succeeds but dependencies fail to build, check the logs: 
superserve agents get my-agent
Look for the deps_status field. If it’s failed, fix your requirements.txt or package.json and redeploy.

​
Missing secrets

If you try to run an agent without setting required secrets: 
✗ Missing required secret(s): ANTHROPIC_API_KEY
Set them with:
┌─────────────────────────────────────────────────────┐
│ superserve secrets set my-agent ANTHROPIC_API_KEY=... │
└─────────────────────────────────────────────────────┘
Set the secrets as shown in the error message.

​
Agent not responding

If your agent starts but doesn’t respond:
  1. Check your agent reads from stdin and writes to stdout
  2. Verify your agent code doesn’t buffer output (use flush=True in Python or disable buffering)
  3. Test locally first: python agent.py or node agent.js

​
Try the Examples

Explore fully-working examples in the Superserve repository:
  • Claude Agent SDK - Conversational agents with tool use
  • OpenAI Agents SDK - Multi-turn agents with function calling
  • Pydantic AI - Type-safe agents with structured outputs
  • Mastra - TypeScript agents with workflow orchestration
  • LangChain - Agents with memory and custom tools
Clone the repo and deploy any example: 
git clone https://github.com/superserve-ai/superserve.git
cd superserve/examples/claude-agent-sdk/chatbot
superserve deploy agent.py --name chatbot
superserve secrets set chatbot ANTHROPIC_API_KEY=sk-ant-...
superserve run chatbot

Build docs developers (and LLMs) love

Get started for freeTalk to us