Examples

// The pattern every solution follows:
create_server  →  prompt / write_file(s)  →  exec  →  deploy
//   get a box       describe or author       run it      live URL

// The simplest path, hand the on-server agent a goal.
// It figures out what to write, install, run, and deploy.

create_server()
// → { "id": "srv_2k9", "tier": "small", "status": "running", "url": null }

prompt({
  server_id: "srv_2k9",
  prompt: "Catch new waitlist submissions, save each event, and alert our Slack channel. Deploy it."
})
// → { "run_id": "run_71a", "status": "running" }

// The on-server agent now:
//  • plans the project
//  • writes the webhook endpoint + event log
//  • installs deps
//  • deploys to a public URL
//  • returns when done

// Bring an existing codebase and let the server figure out how to run it.
create_server()
// → { "id": "srv_2k9", "tier": "small", "status": "running", "url": null }

create_project({
  server_id: "srv_2k9",
  name: "checkout-service",
  source: { kind: "git", git_url: "https://github.com/your-org/checkout-service" }
})
// → { "id": "proj_9f2", "init_run_id": "tsk_c40", "init_phase": "seeding" }

// The on-server agent seeds the workspace, installs deps, starts the app, and
// healthchecks it. Poll get_project until the service is confirmed up:
get_project({ project_id: "proj_9f2" })
// → { "init_phase": "ready",
//     "health": { "listening": true, "last_status": 200 },
//     "url": null }   // set visibility to public for a live URL

// Example 1, write and run a function
// Each line is an MCP tool call your agent makes.

create_server()
// → { "id": "srv_2k9", "tier": "small", "status": "running", "url": null }

write_file({
  server_id: "srv_2k9",
  path: "fib.py",
  content: "def fib(n):\n    a, b = 0, 1\n    for _ in range(n):\n        a, b = b, a + b\n    return a\n\nprint([fib(i) for i in range(10)])"
})
// → { "path": "fib.py", "written": true }

exec({ server_id: "srv_2k9", command: "python fib.py" })
// → { "stdout": "[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]" }

// Example 2, a reusable CSV cleanup portal
write_file({
  server_id: "srv_2k9",
  path: "app.py",
  content: "from flask import Flask, request\n# upload CSV, dedupe, normalize, export cleaned.csv\n..."
})
exec({ server_id: "srv_2k9", command: "flask --app app run --port 8080" })
// → { "stdout": "Running on http://127.0.0.1:8080" }

// Example 3, build and ship a full web app in one call
prompt({
  server_id: "srv_2k9",
  prompt: "Build a Next.js landing page with a waitlist form and deploy it."
})
// → { "run_id": "run_71a", "status": "running" }

// The build agent writes the files, runs the build, and leaves the app
// running. deploy then puts it online: it checks the app is listening,
// makes the project public, and waits for the URL to answer.
deploy({ server_id: "srv_2k9", project_id: "proj_9f2" })
// → { "url": "https://waitlist-9f2.apps.server4agent.com", "status": "live", "project_id": "proj_9f2" }

// Build something bigger, a whole project in one session.
// start_build starts an agent run on the server that works through each stage
// (plan, scaffold, write, install, build and test, start); poll it with get_build.

start_build({ server_id: "srv_2k9", project_id: "proj_9f2",
              goal: "Build a SaaS dashboard with auth and deploy it." })
// → { "build_id": "bld_ep2mrm", "run_id": "tsk_c40", "status": "running", "project_id": "proj_9f2" }

get_build({ server_id: "srv_2k9", build_id: "bld_ep2mrm" })
// → { "status": "running", "run_id": "tsk_c40", "run_status": "running",
//     "steps": [ { "key": "plan", "label": "Plan the project", "status": "running" }, … ] }
// The steps move together; get_run with the run_id shows what the agent is doing now.

// keep polling until status === "completed":
// → { "status": "completed",
//     "url": "https://checkout-service-9f2.apps.server4agent.com",
//     "artifacts": ["app/page.tsx", "app/login/page.tsx", "package.json"],
//     "error": null }
// url is set once the project is public; a failed run reads completed with
// every step "failed", and error says why.

# The same building blocks over plain HTTP (API-key auth, no plan field)
SRV=$(curl -s -X POST https://api.server4agent.com/servers \
  -H "Authorization: Bearer $SERVER4AGENT_API_KEY" | jq -r .id)

curl -X PUT https://api.server4agent.com/servers/$SRV/files \
  -H "Authorization: Bearer $SERVER4AGENT_API_KEY" \
  -d '{ "path": "app.py", "content": "print(\"hello from the agent\")" }'

curl -X POST https://api.server4agent.com/servers/$SRV/exec \
  -H "Authorization: Bearer $SERVER4AGENT_API_KEY" \
  -d '{ "command": "python app.py" }'

curl -X POST https://api.server4agent.com/servers/$SRV/deployments \
  -H "Authorization: Bearer $SERVER4AGENT_API_KEY" \
  -d '{ "project_id": "'$PROJ'" }'
# → { "url": "https://<project>.apps.server4agent.com", "status": "live", "project_id": "..." }