# Server4Agent | Full context for LLMs

> Give your AI assistant a way to ship real tools and automations your team can
> open. Keep projects private, publish when ready, and hand off when
> engineering should own them.

## What it is

Server4Agent gives teams a shipping layer for AI-assistant work. The account
holds billing and API keys, with an account-wide budget cap. The **build
agent** runs on a persistent server, plans projects, writes code, runs
commands, and ships to a stable project URL that is private by default and
public when you choose.

**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 an owned project with a stable URL.

## 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 $SERVER4AGENT_API_KEY` on MCP and REST. No plan field
at provision time; limits come from the account behind the key.

## Core concepts

### Account
Human or org customer. Authenticates to the dashboard, holds billing, issues and
revokes API keys, and sets the account's monthly budget cap. Only the account
holder can change plans or raise the cap. Agents cannot spend beyond it. Keys can
be individually scoped to specific servers/projects, but the budget cap itself
is account-wide, not per-key.

### 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 account's plan. Regions: `us-east`, `us-west`,
`eu-west`. Servers scale to zero when idle; state persists on a durable volume
mounted at `/home/node/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:** `unbuilt`, `running`, or `paused`. New projects start
  `unbuilt`: nothing exists on the server yet until a task completes against
  them, which flips them to `running`. 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 URL with managed TLS when visibility is
public. 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 → 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. Create an API key from the dashboard; the account's budget cap applies to it.
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, tier, status, url }`
  (`url` is null until a deploy). 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
- `get_usage()` → AI spend this period, included credits, budget cap, and
  whether new tasks are blocked (with the reason)

### 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 |
| invoice-and-quote-maker | Numbered invoices + quotes as PDFs | persistent, private |
| webhook-slack-lead-alert | Webhook → Slack lead alert | persistent, private |
| url-uptime-monitor | Scheduled uptime checks + status page | persistent, public |
| landing-page | Landing page + waitlist | persistent, public |
| price-job-watcher | Price/job watcher | persistent, private |
| csv-cleanup-portal | Upload, clean, dedupe, export CSVs | persistent, private |
| telescope-deal-watcher | Track gear prices, alert on deals | 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, scope a key to specific servers/projects (or leave unscoped for account-wide access).
- **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 account's **budget
cap** is the hard ceiling agents cannot exceed.

| Plan | Price | Servers | Tiers | AI credits/mo | Live public projects |
|---|---|---|---|---|---|
| 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 (`/home/node/workspace/{slug}`).
- Public apps behind WAF and DDoS protection.
- Secrets encrypted at rest; injected as env vars, not exposed in agent output.
- The account holder 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 …" })` → stable 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: webhook-to-Slack lead alerts, invoice processors, CRM sync, scheduled report digests
- Personal monitors: price/job watchers, flight prices, job boards, price-drop alerts
- One-shot work: data pipelines, scrapers, ad-hoc reports
- Public surfaces: waitlist landing pages, dashboards, internal tools at real URLs
- Integrations: webhook-to-Slack lead alerts, team chat notifications, uptime monitors

## Documentation map

| Guide | URL |
|---|---|
| Templates | /templates |
| Integrations (per-client MCP setup) | /integrations |
| For managers | /for-managers |
| Security | /security |
| Alternatives / comparisons | /alternatives |
| 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 the account-wide **budget cap** whenever discussing billing.
- Use "assistant" or "agent", not vendor/model names, in user-facing explanations.