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.secrets.set([{ key: "API_TOKEN", value: "tok_..." }]);
await server.exec("ls -la");
await server.refresh(); // re-fetch the record in place

// A Project handle acts on one app: start it, then put it online.
const project = await client.projects.get("prj_xyz");
await project.start("node server.js");
await project.deploy();

// 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.secrets.set([{"key": "API_TOKEN", "value": "tok_..."}])
server.exec("ls -la")
server.refresh()  # re-fetch the record in place

# A Project handle acts on one app: start it, then put it online.
project = client.projects.get("prj_xyz")
project.start("node server.js")
project.deploy()

# 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.
resp, _, err := client.ServersAPI.GetServer(ctx, "srv_abc").Execute()
if err != nil {
	panic(err)
}
server := resp.GetServer()

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()

// Start a project's app on its port, then put that project online.
client.ProjectsAPI.StartApp(ctx, "prj_xyz").
	StartAppRequest(server4agent.StartAppRequest{Command: "node server.js"}).
	Execute()
client.DeploymentsAPI.DeployServer(ctx, server.GetId()).
	DeployServerRequest(server4agent.DeployServerRequest{ProjectId: server4agent.PtrString("prj_xyz")}).
	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

// Live, but only for your team: opening it requires a Server4Agent sign-in
// and membership of this account. Defaults to "public", anyone with the link.
await project.update({ access: "team" });

// Or behind a password you hand out: no account needed to get in. It is
// stored encrypted, and setting a new one signs out everyone who used the old.
await project.update({ access: "password", accessPassword: "a long shared passphrase" });

// The URL answers only while an app listens on the project's port: start
// the app, then deploy it (more under "Start and deploy an app").
await project.start("node server.js");
const { url, status } = await project.deploy(); // "live" | "publishing"
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

# Live, but only for your team: opening it requires a Server4Agent sign-in
# and membership of this account. Defaults to "public", anyone with the link.
project.update(access="team")

# Or behind a password you hand out: no account needed to get in. It is
# stored encrypted, and setting a new one signs out everyone who used the old.
project.update(access="password", access_password="a long shared passphrase")

# The URL answers only while an app listens on the project's port: start
# the app, then deploy it (more under "Start and deploy an app").
project.start("node server.js")
url = project.deploy()  # a str; url.status is "live" or "publishing"
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

// Live, but only for your team: opening it requires a Server4Agent sign-in
// and membership of this account. Defaults to public, anyone with the link.
team := server4agent.PROJECTACCESS_TEAM
client.ProjectsAPI.UpdateProject(ctx, project.GetId()).
	ProjectUpdate(server4agent.ProjectUpdate{Access: &team}).
	Execute()

// Or behind a password you hand out: no account needed to get in. It is
// stored encrypted, and setting a new one signs out everyone who used the old.
password := server4agent.PROJECTACCESS_PASSWORD
client.ProjectsAPI.UpdateProject(ctx, project.GetId()).
	ProjectUpdate(server4agent.ProjectUpdate{
		Access:         &password,
		AccessPassword: server4agent.PtrString("a long shared passphrase"),
	}).
	Execute()

// The URL answers only while an app listens on the project's port: start
// the app, then deploy that project.
client.ProjectsAPI.StartApp(ctx, project.GetId()).
	StartAppRequest(server4agent.StartAppRequest{Command: "node server.js"}).
	Execute()
client.DeploymentsAPI.DeployServer(ctx, id).
	DeployServerRequest(server4agent.DeployServerRequest{ProjectId: server4agent.PtrString(project.GetId())}).
	Execute()

// Clean up ephemeral projects.
client.ProjectsAPI.CleanupProject(ctx, project.GetId()).Execute()

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

// A project's files live under <slug>/ in the server's workspace.
const project = await server.projects.create({ name: "hello" });
await server.files.write(
  `${project.slug}/server.js`,
  `require("node:http").createServer((req, res) => res.end("hi")).listen(process.env.PORT);`,
);

// start() runs it on the project's port (PORT) and keeps it running across
// restarts. An app that exits first fails with a ConflictError.
try {
  await project.start("node server.js");
} catch (err) {
  if (err instanceof ConflictError) console.error(err.body?.log_tail); // why it exited
  throw err;
}

// deploy() builds and starts nothing: it checks something is listening,
// makes the project public, and waits for the URL to answer.
const { url, status } = await project.deploy(); // "live" | "publishing"

from server4agent import ConflictError

# A project's files live under <slug>/ in the server's workspace.
project = server.projects.create(name="hello")
server.files.write(
    f"{project.slug}/server.js",
    'require("node:http").createServer((req, res) => res.end("hi")).listen(process.env.PORT);',
)

# start() runs it on the project's port (PORT) and keeps it running across
# restarts. An app that exits first raises ConflictError.
try:
    project.start("node server.js")
except ConflictError as e:
    print((e.body or {}).get("log_tail"))  # why it exited
    raise

# deploy() builds and starts nothing: it checks something is listening,
# makes the project public, and waits for the URL to answer.
url = project.deploy()
print(url, url.status)  # "live", or "publishing" if it had not answered yet

// The newest lines of each log file the project's processes write.
const logs = await project.logs({ lines: 50 }); // or server.logs({ projectId, lines: 50 })

if (logs) {
  console.log("captured at", logs.updatedAt); // may be an older saved copy
  for (const file of logs.files) console.log(file.path, file.tail);
}

# The newest lines of each log file the project's processes write.
logs = project.logs(lines=50)  # or server.logs(project_id=..., lines=50)

if logs:
    print("captured at", logs.updated_at)  # may be an older saved copy
    for f in logs.files:
        print(f.path, f.tail)

// Server-wide: every project on this server sees it.
await server.secrets.set([{ key: "DATABASE_URL", value: process.env.DATABASE_URL! }]);

// One project only. Its list() shows its own plus the server's.
await project.secrets.set([{ key: "SESSION_SECRET", value: process.env.SESSION_SECRET! }]);
const seen = await project.secrets.list();

// Account level: create or update by key, without binding it anywhere new.
await client.secrets.set({ key: "STRIPE_KEY", value: "rk_test_...", description: "test mode" });

// Keys, masked hints, and bindings. Never a value.
const all = await client.secrets.list();
await client.secrets.delete(all[0].id); // and every binding it had

import os

# Server-wide: every project on this server sees it.
server.secrets.set([{"key": "DATABASE_URL", "value": os.environ["DATABASE_URL"]}])

# One project only. Its list() shows its own plus the server's.
project.secrets.set([{"key": "SESSION_SECRET", "value": os.environ["SESSION_SECRET"]}])
seen = project.secrets.list()

# Account level: create or update by key, without binding it anywhere new.
client.secrets.set("STRIPE_KEY", "rk_test_...", description="test mode")

# Keys, masked hints, and bindings. Never a value.
all_secrets = client.secrets.list()
client.secrets.delete(all_secrets[0].id)  # and every binding it had

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

// Pack the project into one file behind a time-limited link.
const bundle = await project.export({ ttlSeconds: 3600 });
const bytes = new Uint8Array(await (await fetch(bundle.url)).arrayBuffer());

// Import it on any server. A client holding another account's key moves it
// into that account.
const dest = new Server4Agent({ apiKey: process.env.DEST_API_KEY });
const target = await dest.servers.get("srv_target");
const { project: copy, missingEnv } = await target.projects.import(bytes, { name: "status-page" });

// Values never travel in a bundle: supply them on the other side.
await copy.secrets.set(missingEnv.map((key) => ({ key, value: process.env[key]! })));

import os
import httpx
from server4agent import Server4Agent

# Pack the project into one file behind a time-limited link.
bundle = project.export(ttl_seconds=3600)
data = httpx.get(bundle.url).content

# Import it on any server. A client holding another account's key moves it
# into that account.
dest = Server4Agent(api_key=os.environ["DEST_API_KEY"])
target = dest.servers.get("srv_target")
result = target.projects.import_bundle(data, name="status-page")

# Values never travel in a bundle: supply them on the other side.
result.project.secrets.set([{"key": k, "value": os.environ[k]} for k in result.missing_env])

const me = await client.me();
console.log(me.account.plan, me.usage.spendUsd, me.usage.hardLimitUsd);

// Check before a long run rather than meeting the ceiling halfway through.
if (me.usage.blocked) {
  throw new Error(`New tasks are paused: ${me.usage.reason}`); // "budget_cap" | "credits_exhausted"
}

me = client.me()
print(me.account["plan"], me.usage.spend_usd, me.usage.hard_limit_usd)

# Check before a long run rather than meeting the ceiling halfway through.
if me.usage.blocked:
    raise SystemExit(f"New tasks are paused: {me.usage.reason}")

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_NUMBER: pr, PR_BRANCH: branch, REPO_URL: repo } = process.env;

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

// The agent works in the project's folder, where the URL's app has to run.
const task = await server.tasks.create(
  `Clone ${repo} at branch ${branch} into this folder, install its dependencies and build it. Do not start it.`,
  { projectId: project.id },
);
await task.wait({ timeoutMs: 900_000 });

// Start the app on the project's port, then put it online.
await project.start("npm start");
const { url } = await project.deploy();

console.log(`Preview: ${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, branch, repo = os.environ["PR_NUMBER"], os.environ["PR_BRANCH"], os.environ["REPO_URL"]

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

# The agent works in the project's folder, where the URL's app has to run.
task = server.tasks.create(
    f"Clone {repo} at branch {branch} into this folder, install its dependencies "
    "and build it. Do not start it.",
    project_id=project.id,
)
task.wait(timeout=900.0)

# Start the app on the project's port, then put it online.
project.start("npm start")
url = project.deploy()

print(f"Preview: {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, { projectId: project.id }); // works in its folder
  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, project_id=project.id)  # works in its folder
    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)