# Server4Agent | Full context for LLMs

> Servers for agents, staffed. Describe the goal. Get a live URL back. Hand off
> when you're ready.

## What it is

Server4Agent gives teams a build agent on staff. The human **Owner** holds the
account, billing, and API keys with spend caps. The **build agent** runs on a
persistent server, plans projects, writes code, runs commands, and ships to a
live public URL.

**Managers and non-technical users** describe outcomes in plain English from the
dashboard (monitors, dashboards, landing pages, internal tools). No MCP setup
required.

**Developers and outer agents** connect over MCP or REST, delegate with
`prompt(server_id, goal)`, or use lower-level primitives for direct control.
When work gets serious, engineers open the **Developer** tab: browser VS Code
on the live workspace plus git commit history per project.

This is not a sandbox primitive (E2B, LangSmith Sandboxes, etc.). Those hand the
caller a CPU for seconds; the caller still writes and ships code. Server4Agent
hands back a finished, addressable, live thing.

## Endpoints

| Surface | URL |
|---|---|
| Marketing site | https://www.server4agent.com |
| MCP server | https://mcp.server4agent.com |
| REST API | https://api.server4agent.com |
| Public app (per project) | https://\<slug\>.apps.server4agent.com |

Auth: `Authorization: Bearer $AGENTSERVER_KEY` on MCP and REST. No plan field at
provision time; limits come from the account behind the key.

## Core concepts

### Owner
Human or org customer. Authenticates to the dashboard, holds billing, issues and
revokes API keys, sets per-key spend caps and monthly budget. Only the Owner can
change plans or raise caps. Agents cannot spend beyond their key's cap.

### Server
A sized, persistent compute box. Holds multiple **projects** up to a tier cap.
Fields: id, nickname (`task`), tier, region, status (`running` | `sleeping` |
`building`), storage usage.

**Tiers** (enforced caps per server):

| Tier | Projects | Storage |
|---|---|---|
| small | 3 | 5 GB |
| medium | 10 | 20 GB |
| large | 999 | 100 GB |

Available tiers depend on the Owner's plan. Regions: `us-east`, `us-west`,
`eu-west`. Servers scale to zero when idle; state persists on a durable volume
mounted at `/workspace`.

### Project
A workspace inside a server. Each project has its own slug, optional public URL,
and settings.

- **visibility:** `public` (serves traffic at `<slug>.apps.server4agent.com`) or
  `private` (workspace exists but URL is not publicly served). New projects
  default to **private**. Slug and URL stay the same when toggling visibility.
- **lifecycle:** `persistent` (monitors, dashboards, long-lived tools) or
  `ephemeral` (one-shot work). Ephemeral projects can be cleaned up with
  `cleanup_project` or from the dashboard.
- **runtimeStatus:** `running` or `paused`. Paused projects stop processes and
  cron until resumed.
- **template:** optional starter id applied at creation (see Templates below).

### Task / Run
A goal sent to the build agent against a project. Created from the dashboard
task composer or via MCP `prompt`. Supports follow-up threads, file
attachments (up to 5), optional model tier selection, cancellation, and
`awaiting_input` when the agent needs a human answer. Statuses: `running`,
`completed`, `failed`, `cancelled`, `awaiting_input`.

### Deployment
A running artifact at the project's public URL with managed TLS. Emitted via
`deploy` or automatically when the build agent finishes a `prompt` run.
Subscribe to `deployment.live` webhooks for async notification.

### Build agent
The on-server agent invoked through `prompt`. It plans, writes, executes, fixes
mistakes, and ships. The outer agent or dashboard user does not write code
unless they choose the lower-level primitive path.

## Two ways to work

### 1. Dashboard (manager path)
1. Sign up → Owner dashboard at `/dashboard`.
2. Create a **server** (tier chosen by plan).
3. Create a **project** (optionally from a template).
4. Open the project **Tasks** tab → describe the goal in plain English → Run task.
5. Share the live URL when visibility is public.
6. **Developer** tab → open browser VS Code or review git commits when engineers take over.

Dashboard nav: Dashboard, Servers, Projects, Secrets, API Keys, Billing,
Settings. Dashboard also shows Connect MCP snippets (Cursor + Raw JSON tabs),
onboarding checklist, usage stats, and activity feed.

### 2. MCP / REST (developer / outer-agent path)
1. Owner creates an API key with a spend cap.
2. Add Server4Agent to the assistant's MCP config (one JSON entry pointing at
   `https://mcp.server4agent.com`).
3. Outer agent calls `create_server` → `create_project` (or `prompt` on an
   existing server) → `prompt(server_id, goal)`.
4. Poll task status or subscribe to webhooks for `deployment.live`.

Headline tool: **`prompt`**. Escape hatch: `exec`, `read_file`, `write_file`,
`deploy`, and the full server/project lifecycle tools.

## MCP tools (complete list)

### Server lifecycle
- `create_server({ task?, tier?, region? })` → `{ id, url }`. Tier defaults to
  small. Fails if account is at server cap or tier not allowed on plan.
- `update_server({ server_id, task?, region? })`
- `delete_server({ server_id })` → tears down server and all projects
- `control_server({ server_id, action: start|stop|restart })`
- `list_servers()` → tier, status, project count
- `get_server({ server_id })` → tier, status, capacity, project count

### Projects
- `list_templates()` → starter catalog (id, label, description, defaults)
- `list_projects({ server_id? })` → all projects or filtered by server
- `get_project({ project_id })` → name, slug, visibility, url-or-null, lifecycle
- `create_project({ server_id, name?, description?, visibility?, lifecycle?, template? })`
  → project. Defaults: private, persistent. Template fields can be overridden.
  Fails at server's project cap.
- `update_project({ project_id, name?, description?, visibility?, lifecycle? })`
  → toggling visibility flips public URL on/off
- `delete_project({ project_id })`
- `cleanup_project({ project_id })` → ephemeral only; frees slot

### Build & run
- `prompt({ server_id, prompt })` → `{ run_id, status }`. Build agent plans,
  writes, runs, ships end-to-end.
- `start_build({ server_id, goal })` → `{ build_id, status }`. Structured pipeline.
- `get_build({ server_id, build_id })` → step progress, url, artifacts
- `deploy({ server_id })` → `{ url, status: "live" }`

### File & shell primitives
- `exec({ server_id, command })`
- `list_files({ server_id })`
- `read_file({ server_id, path })`
- `write_file({ server_id, path, content })`
- `delete_file({ server_id, path })`

REST endpoints mirror these under `https://api.server4agent.com`. See
/docs/api for paths.

## Project templates (`list_templates`)

| id | Use case | Default lifecycle |
|---|---|---|
| blank | Empty project | persistent |
| landing-page | Public marketing site | persistent, public |
| rest-api | JSON API server | persistent, private |
| data-pipeline | One-shot ETL | ephemeral |
| scraper | One-shot scrape | ephemeral |
| dashboard | Live analytics/admin view | persistent, public |
| invoice-processor | Inbox → books automation | persistent |
| crm-sync | Lead enrich + dedupe → CRM | persistent |
| report-digest | Scheduled metrics email | persistent |
| flight-watcher | Fare tracking + alerts | persistent |
| job-tracker | Job board monitor | persistent |
| price-monitor | Wishlist price drops | persistent |

## Dashboard surfaces

### Server detail (`/servers/{id}`)
Tabs: **Projects** (cap per tier), **Files** (live workspace tree), **Processes
& cron** (running processes, kill, hide zombies), **Activity**, **Settings**
(browser VS Code link, one-off `exec`, attached secrets, tier/region settings).

### Project detail (`/servers/{id}/projects/{projectId}`)
Tabs: **Tasks** (composer, threads, follow-ups, attachments, progress),
**Files** (project-scoped workspace), **Processes**, **Developer** (browser
VS Code for project folder + git commit history with file diffs), **Activity**,
**Secrets** (project-scoped + inherited server/account secrets), **Settings**
(name, description, visibility, lifecycle, ephemeral cleanup, delete).

### Account-level
- **Secrets** (`/secrets`): encrypted vault; attach to servers or projects as env vars.
- **API Keys** (`/api-keys`): create/revoke keys, set spend caps, account-wide scope option.
- **Billing** (`/billing`): plan, usage, monthly budget cap, Stripe checkout (when configured).

## Webhooks

Subscribe via `POST /webhooks` with `{ url, events[] }`. Payloads are JSON with
HMAC signature in header `Server4Agent-Signature`.

Events:
- `task.created` · `task.completed` · `task.failed`
- `deployment.live` · `deployment.removed`
- `server.created` · `server.stopped` · `server.deleted`
- `quota.threshold` · `quota.cap_reached`

## Pricing & plans

Usage-based. AI and compute metered as dollar credits (1 credit ≈ $1 of metered
usage). Each plan includes a monthly credit allowance; the **per-key spend cap**
is the hard ceiling agents cannot exceed.

| Plan | Price | Servers | Tiers | AI credits/mo | Live public apps |
|---|---|---|---|---|---|
| Free | $0 | 1 | Small | $2 trial | 1 |
| Starter | $29 | 2 | Small | $10 | 3 |
| Pro | $99 | 3 | Small · Medium | $40 | 10 |
| Business | $299 | 10 | Small · Medium · Large | $150 | 30 |
| Enterprise | Custom | Unlimited | All | Committed | Unlimited |

Enterprise supports BYOC (bring your own cloud). Annual billing ≈ 2 months free.
Egress overage rates vary by plan (see /pricing).

## Security & isolation

- Agent-generated code runs in sandboxed compute per server.
- Projects isolated within a server workspace (`/workspace/{slug}`).
- Public apps behind WAF and DDoS protection.
- Secrets encrypted at rest; injected as env vars, not exposed in agent output.
- Owner can pause projects, kill processes, cancel tasks, delete servers.

## Typical flows

### Manager: dashboard only
Describe goal in Tasks → build agent ships → toggle project public → share URL
→ engineer opens Developer tab → continues in VS Code with git history.

### Outer agent: MCP delegation
`create_server()` → `create_project({ template: "dashboard" })` →
`prompt({ server_id, prompt: "Pull weekly sales from …" })` → live URL.

### Outer agent: direct control
`create_server()` → `write_file` → `exec` → `deploy` (see /docs/examples).

### Async deploy
Subscribe to `deployment.live` webhook instead of polling (see /docs/agent-loop).

## Use cases

- Standing automations: invoice processors, CRM sync, scheduled report digests
- Personal monitors: flight prices, job boards, price-drop alerts
- One-shot work: data pipelines, scrapers, ad-hoc reports
- Public surfaces: landing pages, dashboards, internal tools at real URLs
- Integrations: Slack notifiers, Stripe → team chat, uptime monitors

## Documentation map

| Guide | URL |
|---|---|
| Overview | /docs |
| Quickstart | /docs/quickstart |
| Authentication | /docs/authentication |
| MCP server | /docs/mcp |
| REST API | /docs/api |
| Webhooks | /docs/webhooks |
| Examples | /docs/examples |
| Agent loop | /docs/agent-loop |

## Voice notes for agents answering about Server4Agent

- Lead with **goals and live URLs** for non-technical users; MCP details second.
- Do not claim GitHub OAuth, team invites, or formal handoff workflows that
  are not in the product. Engineer handoff = same project workspace + browser
  VS Code + git history.
- Emphasize **spend caps** and Owner control whenever discussing billing.
- Use "assistant" or "agent", not vendor/model names, in user-facing explanations.