SDKs

npm install @server4agent/sdk

pip install server4agent

go get github.com/Server4Agent/server4agent-go

import { Server4Agent } from "@server4agent/sdk";

// With no arguments, reads SERVER4AGENT_API_KEY from the environment.
const client = new Server4Agent();

// Or pass the key and tune the transport explicitly.
const tuned = new Server4Agent({
  apiKey: process.env.SERVER4AGENT_API_KEY,
  timeoutMs: 30_000, // per-request timeout (default 60_000)
  maxRetries: 4,     // retries on 429/5xx/network (default 2)
});

from server4agent import Server4Agent

# With no arguments, reads SERVER4AGENT_API_KEY from the environment.
client = Server4Agent()

# Or pass the key and tune the transport explicitly.
tuned = Server4Agent(
    api_key="sk_live_...",
    timeout=30.0,   # per-request timeout in seconds (default 60)
    max_retries=4,  # retries on 429/5xx/network (default 2)
)

# Use it as a context manager to close the connection pool when you're done.
with Server4Agent() as client:
    ...

package main

import (
	"context"
	"os"

	server4agent "github.com/Server4Agent/server4agent-go"
)

func main() {
	// NewConfiguration() targets api.server4agent.com by default.
	client := server4agent.NewAPIClient(server4agent.NewConfiguration())

	// The generated client authenticates with a context value, not a
	// constructor arg: put your sk_live_ key on the context as a bearer token
	// and pass that ctx to every call. Keep it server-side.
	ctx := context.WithValue(context.Background(),
		server4agent.ContextAccessToken, os.Getenv("SERVER4AGENT_API_KEY"))

	_, _ = client, ctx
}

import { Server4Agent } from "@server4agent/sdk";

const client = new Server4Agent();

// create() resolves to a handle you can act on directly.
const server = await client.servers.create({ tier: "small" });

// Hand the on-server agent a goal and block until it's live.
const build = await server.builds.start("a FastAPI todo API with a small web UI");
await build.wait({ onProgress: (b) => console.log("build:", b.status) });

console.log("live at", build.url);

from server4agent import Server4Agent

client = Server4Agent()

# create() returns a handle you can act on directly.
server = client.servers.create(tier="small")

# Hand the on-server agent a goal and block until it's live.
build = server.builds.start("a FastAPI todo API with a small web UI")
build.wait(on_poll=lambda b: print("build:", b.status))

print("live at", build.url)

client := server4agent.NewAPIClient(server4agent.NewConfiguration())
ctx := context.WithValue(context.Background(),
	server4agent.ContextAccessToken, os.Getenv("SERVER4AGENT_API_KEY"))

// Provision a server.
tier := server4agent.SERVERTIER_SMALL
server, _, err := client.ServersAPI.CreateServer(ctx).
	ServerCreate(server4agent.ServerCreate{Tier: &tier}).
	Execute()
if err != nil {
	panic(err)
}

// Hand the on-server agent a goal.
build, _, err := client.BuildsAPI.StartBuild(ctx, server.GetId()).
	BuildCreate(server4agent.BuildCreate{Goal: "a FastAPI todo API with a small web UI"}).
	Execute()
if err != nil {
	panic(err)
}

// The generated client has no .wait(): poll BuildsAPI.GetBuild until the
// status is completed, then read the live url off the finished build.
fmt.Println("build", build.GetBuildId(), build.GetStatus())

// create() and get() both resolve to a Server handle.
const server = await client.servers.get("srv_abc");

// Its sub-resources are already scoped to it: no id to pass again.
await server.tasks.create("Summarize today's sales into report.md");
await server.files.write("notes.txt", "hello");
await server.exec("ls -la");
await server.deploy();
await server.refresh(); // re-fetch the record in place

// Prefer passing ids around? The flat API takes a server id up front.
await client.tasks.create(server.id, "Same task, id passed explicitly.");
await client.files.write(server.id, "notes.txt", "hello");

# create() and get() both return a Server handle.
server = client.servers.get("srv_abc")

# Its sub-resources are already scoped to it: no id to pass again.
server.tasks.create("Summarize today's sales into report.md")
server.files.write("notes.txt", "hello")
server.exec("ls -la")
server.deploy()
server.refresh()  # re-fetch the record in place

# Prefer passing ids around? The flat API takes a server id up front.
client.tasks.create(server.id, "Same task, id passed explicitly.")
client.files.write(server.id, "notes.txt", "hello")

// The generated Go client has no handle objects. Everything is a per-resource
// service call that takes the ids explicitly, which is the same "flat" form the
// TypeScript and Python clients also expose.
server, _, err := client.ServersAPI.GetServer(ctx, "srv_abc").Execute()
if err != nil {
	panic(err)
}

client.TasksAPI.CreateTask(ctx, server.GetId()).
	TaskCreate(server4agent.TaskCreate{Goal: "Summarize today's sales into report.md"}).
	Execute()

client.FilesAPI.WriteFile(ctx, server.GetId()).
	FileWrite(server4agent.FileWrite{Path: "notes.txt", Content: "hello"}).
	Execute()

client.DeploymentsAPI.DeployServer(ctx, server.GetId()).Execute()

// tier sizes the box: "small" | "medium" | "large". task is a label.
const server = await client.servers.create({ tier: "medium", task: "data pipeline" });

const all = await client.servers.list();
const one = await client.servers.get(server.id);

// Lifecycle controls.
await server.stop();
await server.start();
await server.restart();

// Rename, re-fetch, tear down.
await server.update({ task: "renamed pipeline" });
await server.refresh();
await server.delete();

# tier sizes the box: "small" | "medium" | "large". task is a label.
server = client.servers.create(tier="medium", task="data pipeline")

all_servers = client.servers.list()
one = client.servers.get(server.id)

# Lifecycle controls.
server.stop()
server.start()
server.restart()

# Rename, re-fetch, tear down.
server.update(task="renamed pipeline")
server.refresh()
server.delete()

// tier sizes the box; task is a human-readable label. Optional fields are
// pointers, so take their address (or use server4agent.PtrString / Ptr*).
tier := server4agent.SERVERTIER_MEDIUM
task := "data pipeline"
created, _, err := client.ServersAPI.CreateServer(ctx).
	ServerCreate(server4agent.ServerCreate{Tier: &tier, Task: &task}).
	Execute()
if err != nil {
	panic(err)
}
id := created.GetId()

// List and get return the wrapped payloads.
list, _, _ := client.ServersAPI.ListServers(ctx).Execute()
one, _, _ := client.ServersAPI.GetServer(ctx, id).Execute()
_, _ = list.GetServers(), one.GetServer()

// Lifecycle: start / stop / restart.
client.ServersAPI.ControlServer(ctx, id).
	ServerActionRequest(server4agent.ServerActionRequest{
		Action: server4agent.SERVERACTIONREQUESTACTION_STOP,
	}).
	Execute()

// Rename, then tear down.
newTask := "renamed pipeline"
client.ServersAPI.UpdateServer(ctx, id).
	ServerUpdate(server4agent.ServerUpdate{Task: &newTask}).
	Execute()
client.ServersAPI.DeleteServer(ctx, id).Execute()

// exec() runs a shell command on the server and resolves to stdout.
await server.exec("pip install httpx");
const out = await server.exec("python -c 'import sys; print(sys.version)'");
console.log(out);

# exec() runs a shell command on the server and returns stdout.
server.exec("pip install httpx")
out = server.exec("python -c 'import sys; print(sys.version)'")
print(out)

// ExecCommand runs a shell command on the server and returns its stdout.
res, _, err := client.ServersAPI.ExecCommand(ctx, id).
	ExecRequest(server4agent.ExecRequest{
		Command: "python -c 'import sys; print(sys.version)'",
	}).
	Execute()
if err != nil {
	panic(err)
}
fmt.Println(res.GetStdout())

// The workspace is durable: files and installed deps survive between tasks.
await server.files.write("app.py", "print('hello from the server')");

const listing = await server.files.list();     // string[] of paths
const content = await server.files.read("app.py");
await server.files.delete("app.py");

# The workspace is durable: files and installed deps survive between tasks.
server.files.write("app.py", "print('hello from the server')")

listing = server.files.list()      # list[str] of paths
content = server.files.read("app.py")
server.files.delete("app.py")

// Write a file into the durable workspace.
client.FilesAPI.WriteFile(ctx, id).
	FileWrite(server4agent.FileWrite{
		Path:    "app.py",
		Content: "print('hello from the server')",
	}).
	Execute()

// readOrListFiles: with a path it reads that file; without one it lists the
// workspace. deleteFile takes the path as a query param too.
client.FilesAPI.ReadOrListFiles(ctx, id).Path("app.py").Execute()
client.FilesAPI.ReadOrListFiles(ctx, id).Execute() // list everything
client.FilesAPI.DeleteFile(ctx, id).Path("app.py").Execute()

// A task hands the on-server agent a goal. wait() polls until it settles.
const task = await server.tasks.create("Scrape today's HN front page to hn.json.");
await task.wait({ onProgress: (t) => console.log("task:", t.status) });

// Terminal states: completed, failed, cancelled, awaiting_input.
if (task.status === "completed") {
  console.log(task.result);
} else if (task.status === "awaiting_input") {
  // The agent needs a decision from you before it can continue.
  console.log("agent asks:", task.question);
}

# A task hands the on-server agent a goal. wait() polls until it settles.
task = server.tasks.create("Scrape today's HN front page to hn.json.")
task.wait(on_poll=lambda t: print("task:", t.status))

# Terminal states: completed, failed, cancelled, awaiting_input.
if task.status == "completed":
    print(task.result)
elif task.status == "awaiting_input":
    # The agent needs a decision from you before it can continue.
    print("agent asks:", task.question)

// Hand the on-server agent a goal.
created, _, err := client.TasksAPI.CreateTask(ctx, id).
	TaskCreate(server4agent.TaskCreate{
		Goal: "Scrape today's HN front page to hn.json.",
	}).
	Execute()
if err != nil {
	panic(err)
}

// The generated client has no .wait(): poll TasksAPI.GetTask(ctx, id,
// created.GetTaskId()) on an interval until the status is terminal:
// completed, failed, cancelled, or awaiting_input (the agent needs a decision).
fmt.Println("task", created.GetTaskId(), created.GetStatus())

// A build runs an ordered pipeline: plan, scaffold, implement, install,
// build, deploy. Stream step-by-step progress through onProgress.
const build = await server.builds.start("Build a SaaS dashboard with auth and deploy it.");

await build.wait({
  timeoutMs: 900_000,
  onProgress: (b) => {
    const step = b.steps.find((s) => s.status === "running");
    console.log("building:", step?.label ?? b.status);
  },
});

console.log("live at", build.url);
console.log("artifacts:", build.artifacts); // e.g. ["app/page.tsx", "package.json"]

# A build runs an ordered pipeline: plan, scaffold, implement, install,
# build, deploy. Stream step-by-step progress through on_poll.
build = server.builds.start("Build a SaaS dashboard with auth and deploy it.")


def show(b):
    running = next((s for s in b.steps if s.status == "running"), None)
    print("building:", running.label if running else b.status)


build.wait(timeout=900.0, on_poll=show)

print("live at", build.url)
print("artifacts:", build.artifacts)  # e.g. ["app/page.tsx", "package.json"]

// A build runs an ordered pipeline: plan, scaffold, implement, install,
// build, deploy.
created, _, err := client.BuildsAPI.StartBuild(ctx, id).
	BuildCreate(server4agent.BuildCreate{
		Goal: "Build a SaaS dashboard with auth and deploy it.",
	}).
	Execute()
if err != nil {
	panic(err)
}

// Poll BuildsAPI.GetBuild(ctx, id, created.GetBuildId()) until the status is
// completed. The finished Build carries per-step status, GetArtifacts(), and
// the live GetUrl().
fmt.Println("build", created.GetBuildId(), created.GetStatus())

// A project is a workspace + app inside a server. New projects are PRIVATE:
// url is null until you publish. Start from a template if you like.
const templates = await client.templates.list();
const project = await server.projects.create({
  name: "status-page",
  template: "dashboard",
  // visibility defaults to "private"; lifecycle defaults to "persistent".
});

console.log(project.url); // null while private

// Publish it. The slug and URL stay stable across visibility toggles.
await project.update({ visibility: "public" });
await project.refresh();
console.log(project.url); // https://<slug>.apps.server4agent.com

// Deploy the current workspace to a live URL, list deployments.
const url = await server.deploy();
const history = await server.deployments();

// Ephemeral projects clean up with cleanup(); persistent ones with delete().
await project.cleanup();

# A project is a workspace + app inside a server. New projects are PRIVATE:
# url is None until you publish. Start from a template if you like.
templates = client.templates.list()
project = server.projects.create(
    name="status-page",
    template="dashboard",
    # visibility defaults to "private"; lifecycle defaults to "persistent".
)

print(project.url)  # None while private

# Publish it. The slug and URL stay stable across visibility toggles.
project.update(visibility="public")
project.refresh()
print(project.url)  # https://<slug>.apps.server4agent.com

# Deploy the current workspace to a live URL, list deployments.
url = server.deploy()
history = server.deployments()

# Ephemeral projects clean up with cleanup(); persistent ones with delete().
project.cleanup()

// A project is a workspace + app inside a server. New projects are PRIVATE:
// GetUrl() is empty until you publish. Optional fields use the Ptr* helpers.
project, _, err := client.ProjectsAPI.CreateProject(ctx, id).
	ProjectCreate(server4agent.ProjectCreate{
		Name:     server4agent.PtrString("status-page"),
		Template: server4agent.PtrString("dashboard"),
	}).
	Execute()
if err != nil {
	panic(err)
}
fmt.Println(project.GetUrl()) // empty while private

// Publish it. The slug and URL stay stable across visibility toggles.
pub := server4agent.PROJECTVISIBILITY_PUBLIC
updated, _, _ := client.ProjectsAPI.UpdateProject(ctx, project.GetId()).
	ProjectUpdate(server4agent.ProjectUpdate{Visibility: &pub}).
	Execute()
fmt.Println(updated.GetUrl()) // https://<slug>.apps.server4agent.com

// Deploy the workspace; clean up ephemeral projects.
client.DeploymentsAPI.DeployServer(ctx, id).Execute()
client.ProjectsAPI.CleanupProject(ctx, project.GetId()).Execute()

import {
  Server4AgentError,
  NotFoundError,
  RateLimitError,
  APIStatusError,
} from "@server4agent/sdk";

try {
  await client.servers.get("srv_does_not_exist");
} catch (err) {
  if (err instanceof NotFoundError) {
    // 404
  } else if (err instanceof RateLimitError) {
    // 429, already retried; quote err.requestId to support
  } else if (err instanceof APIStatusError) {
    console.error(err.status, err.code, err.message, err.requestId);
  } else if (err instanceof Server4AgentError) {
    // anything else from the SDK (timeouts, network)
  }
}

from server4agent import (
    Server4AgentError,
    NotFoundError,
    RateLimitError,
    APIStatusError,
)

try:
    client.servers.get("srv_does_not_exist")
except NotFoundError:
    ...  # 404
except RateLimitError as e:
    ...  # 429, already retried; quote e.request_id to support
except APIStatusError as e:
    print(e.status, e.code, e.message, e.request_id)
except Server4AgentError:
    ...  # anything else from the SDK (timeouts, network)

// Every call returns the model, the raw *http.Response, and an error.
_, httpResp, err := client.ServersAPI.GetServer(ctx, "srv_does_not_exist").Execute()
if err != nil {
	// Decode the typed API error for the raw body (and the JSON Error model).
	var apiErr server4agent.GenericOpenAPIError
	if errors.As(err, &apiErr) {
		fmt.Println("body:", string(apiErr.Body()))
	}
	// The response is still available for the status code: 404, 429, 5xx, …
	if httpResp != nil {
		fmt.Println("status:", httpResp.StatusCode)
	}
}

import asyncio
from server4agent import AsyncServer4Agent

# The async client mirrors the sync one method-for-method; every call awaits.
async def main():
    async with AsyncServer4Agent() as client:
        server = await client.servers.create(tier="small")
        task = await server.tasks.create("Summarize today's top HN posts to summary.md")
        await task.wait(on_poll=lambda t: print("task:", t.status))
        print(task.result)

asyncio.run(main())

// The JS client is already promise-based: every method returns a Promise,
// so there's no separate async client. Just await.
const server = await client.servers.create({ tier: "small" });
const task = await server.tasks.create("Summarize today's top HN posts to summary.md");
await task.wait();
console.log(task.result);

// Go has no async client either: concurrency is goroutines. Every call already
// takes a context, so fan out in parallel and cancel with the context.
var wg sync.WaitGroup
for _, goal := range goals {
	wg.Add(1)
	go func(goal string) {
		defer wg.Done()
		client.TasksAPI.CreateTask(ctx, id).
			TaskCreate(server4agent.TaskCreate{Goal: goal}).
			Execute()
	}(goal)
}
wg.Wait()

import { verifyWebhookSignature } from "@server4agent/sdk";

// req.text() must be the RAW body. Verify before you JSON.parse it:
// re-serializing changes the bytes and breaks the signature.
const raw = await req.text();
const ok = await verifyWebhookSignature(
  process.env.SERVER4AGENT_WEBHOOK_SECRET!,
  raw,
  req.headers.get("server4agent-signature"),
);
if (!ok) return new Response("invalid signature", { status: 401 });

const event = JSON.parse(raw);

import os
from server4agent import verify_webhook_signature

# request.data must be the RAW body. Verify before you json.loads it:
# re-serializing changes the bytes and breaks the signature.
ok = verify_webhook_signature(
    secret=os.environ["SERVER4AGENT_WEBHOOK_SECRET"],
    body=request.data.decode("utf-8"),
    header=request.headers.get("Server4Agent-Signature"),
)
if not ok:
    return "invalid signature", 401

// The signature helper ships in the Python and JavaScript clients. From Go,
// verify the Server4Agent-Signature header against the RAW request body
// yourself, using the scheme in the Webhooks guide, before you decode the JSON.
//
//   raw, _ := io.ReadAll(r.Body)
//   if !verifySignature(secret, raw, r.Header.Get("Server4Agent-Signature")) {
//       http.Error(w, "invalid signature", http.StatusUnauthorized)
//       return
//   }
//   var event map[string]any
//   json.Unmarshal(raw, &event)

// Run from CI on every PR: give it a real, disposable URL, then tear it
// down when the PR closes. lifecycle "ephemeral" marks it for cleanup.
import { Server4Agent } from "@server4agent/sdk";

const client = new Server4Agent();
const pr = process.env.PR_NUMBER!;

const server = await client.servers.create({ task: `pr-${pr}` });
const project = await server.projects.create({
  name: `pr-${pr}`,
  visibility: "public",
  lifecycle: "ephemeral",
});

const build = await server.builds.start("Install deps, build the app, and deploy it.");
await build.wait();

console.log(`Preview: ${project.url}`);
// On PR close: await project.cleanup();

# Run from CI on every PR: give it a real, disposable URL, then tear it
# down when the PR closes. lifecycle "ephemeral" marks it for cleanup.
import os
from server4agent import Server4Agent

client = Server4Agent()
pr = os.environ["PR_NUMBER"]

server = client.servers.create(task=f"pr-{pr}")
project = server.projects.create(
    name=f"pr-{pr}",
    visibility="public",
    lifecycle="ephemeral",
)

build = server.builds.start("Install deps, build the app, and deploy it.")
build.wait()

print(f"Preview: {project.url}")
# On PR close: project.cleanup()

import express from "express";
import { verifyWebhookSignature } from "@server4agent/sdk";

const app = express();

app.post("/hooks/server4agent", express.text({ type: "*/*" }), async (req, res) => {
  // req.body must be the raw string; verify before you JSON.parse it.
  const ok = await verifyWebhookSignature(
    process.env.SERVER4AGENT_WEBHOOK_SECRET!,
    req.body,
    req.header("Server4Agent-Signature"),
  );
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body);
  if (event.event === "deployment.live") {
    await notifySlack(`Deployed: ${event.url}`);
  }
  res.status(200).end();
});

import json
import os
from flask import Flask, request
from server4agent import verify_webhook_signature

app = Flask(__name__)


@app.post("/hooks/server4agent")
def hook():
    # request.get_data() must be the raw body; verify before you json.loads it.
    raw = request.get_data(as_text=True)
    ok = verify_webhook_signature(
        os.environ["SERVER4AGENT_WEBHOOK_SECRET"],
        raw,
        request.headers.get("Server4Agent-Signature"),
    )
    if not ok:
        return "invalid signature", 401

    event = json.loads(raw)
    if event["event"] == "deployment.live":
        notify_slack(f"Deployed: {event['url']}")
    return "", 200

// Your product's backend, not an agent: a customer submits a request, your
// own business logic decides what to build, and you provision a real
// workspace for them on demand.
import { Server4Agent } from "@server4agent/sdk";

const client = new Server4Agent();

export async function provisionForCustomer(customerId: string, goal: string) {
  const server = await client.servers.create({ task: `customer-${customerId}` });
  const project = await server.projects.create({
    name: `${customerId}-workspace`,
    visibility: "public",
    template: "dashboard",
  });
  await server.tasks.create(goal);
  return project.url;
}

# Your product's backend, not an agent: a customer submits a request, your
# own business logic decides what to build, and you provision a real
# workspace for them on demand.
from server4agent import Server4Agent

client = Server4Agent()


def provision_for_customer(customer_id: str, goal: str) -> str:
    server = client.servers.create(task=f"customer-{customer_id}")
    project = server.projects.create(
        name=f"{customer_id}-workspace",
        visibility="public",
        template="dashboard",
    )
    server.tasks.create(goal)
    return project.url

// Hand a support tool a key that can only touch one customer's server,
// not your whole account.
const supportKey = await client.keys.create("support-tool");
await client.keys.updateScope(supportKey.id, {
  allowedServerIds: [server.id],
});

// supportKey.key is the plaintext, shown once, here. Hand it to the tool
// and store the id if you'll need to revoke it later.
// await client.keys.revoke(supportKey.id);

# Hand a support tool a key that can only touch one customer's server,
# not your whole account.
support_key = client.keys.create("support-tool")
client.keys.update_scope(support_key.id, allowed_server_ids=[server.id])

# support_key.key is the plaintext, shown once, here. Hand it to the tool
# and store the id if you'll need to revoke it later.
# client.keys.revoke(support_key.id)