Agent deployment

Agent Integration Guide

Give an external agent or CI runner a scoped STATICX token, project ID, and deployment contract so it can upload, deploy, and inspect a static site through the API.

Agent deployment

Give an agent the same release contract your dashboard uses.

Agents should build locally, upload the output ZIP, publish, inspect logs, and return the live URL or the exact API error.

Auth

API token

Contract

/api/v1

Input

ZIP output

Dashboard path

Open Project Settings → Agent deploy.

The project page gives everything an agent needs: project ID, API base URL, current live URL, a generated token flow, the filled text instruction, and MCP config.

Recommended setup

Create one scoped token per agent or automation runner.

Create a site token. Use the project Agent deploy tab when the automation only needs one site.
Default to Full access on that site token. It covers upload, deploy, and logs for the site-scoped release flow.
Escalate only when needed. Move to a Workspace token only when the runner truly needs several sites inside one workspace, or to a Global token for broad internal operator flows.
Store it safely. The token is shown once. Put it in the agent environment or secret manager.
Copy the project instruction. The project tab fills in the project ID, base URL, and live URL.
Run the deployment. The agent should build, confirm 404.html, zip, upload, deploy, and verify logs.
Revoke when done. Delete old tokens from the project page or from Settings to remove access.

CLI alternative

Use the public npm CLI when the runner prefers terminal commands.

The site and workspace Agent deploy pages now expose both the text-only agent prompt and a ready-made CLI block with the same token scope.

npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx guide
staticx whoami
staticx deploy --site-id STATICX_PROJECT_ID --dir dist
staticx domain --site-id STATICX_PROJECT_ID --domain app.example.com
staticx domain-status --site-id STATICX_PROJECT_ID
staticx logs --site-id STATICX_PROJECT_ID

Scope guide

Use the smallest scope that still lets the agent finish.

Site token

Best default for one build pipeline or one deployment bot tied to a single site.

Workspace token

Use only when one tool must create or update multiple sites inside one workspace. This is the right middle ground between one-site deploy bots and broad account automation.

Global token

Reserve for broad internal tooling or admin-controlled workflows that must cross workspace boundaries, not routine deploy agents.

Copyable instruction

Text-only agent prompt.

Use this format when the agent does not support MCP tools. Replace the token and project ID, or copy the filled version from a project page.

Instruction

Deploy `dist` to StaticX project `STATICX_PROJECT_ID` using `STATICX_API_TOKEN`.

Use:
- https://staticx.site/llms.txt
- https://staticx.site/llms-full.txt
- https://staticx.site/api/v1/openapi.json

Build, validate `index.html` + `404.html`, apply StaticX form rules if forms exist, zip `dist` root, upload, deploy, check logs, then return the live URL or the exact API error. Never expose the token.

Context:
- API Base URL: https://staticx.site/api/v1
- Authentication: Bearer STATICX_API_TOKEN
- Project ID: STATICX_PROJECT_ID
- Build output directory: dist

Endpoint reference:
- GET /projects/{project} - confirm project state.
- POST /projects/{project}/files - upload the build ZIP with multipart fields mode=zip, overwrite_confirmed=1, and [email protected].
- POST /projects/{project}/deployments - publish a new version.
- GET /projects/{project}/deployments - read deployment history.
- POST /projects/{project}/domain - move the site to a custom domain when requested.
- GET /projects/{project}/domain - read custom domain activation status.
- GET /projects/{project}/logs - read project logs.

StaticX form rules:
- If forms exist, add data-staticx-form to each form that should collect entries.
- Use data-staticx-form-id="contacts" only when several pages should share one collection.
- Give every input, textarea, and select a stable name attribute.
- Keep the form as normal HTML. Do not wire it to a custom backend endpoint.
- Optional attributes: data-staticx-success-message, data-staticx-error-message, and data-staticx-redirect.
- Do not manually inject the StaticX script or action.
- After deployment, submit one test entry and confirm the collection appears in the Forms tab.

Steps:
1. Build the project locally.
2. Confirm the build output contains index.html or index.htm plus 404.html at the root.
3. Zip the contents of the build output directory so those root files stay at the ZIP root.
4. Upload the ZIP with POST /projects/{project}/files using mode=zip, overwrite_confirmed=1, and [email protected].
5. Deploy with POST /projects/{project}/deployments.
6. If the user wants a custom domain, call POST /projects/{project}/domain and return the DNS record to create.
7. Check GET /projects/{project}/deployments and GET /projects/{project}/logs.
8. Return the live URL, domain instructions, or the exact API error message if deployment fails.

Agent rules

What the agent should and should not do.

Do

Build the project locally before upload.
Make sure index.html or index.htm and 404.html are both at the build output root.
Zip the build output contents so those required files are at the archive root.
Deploy directly with POST /projects/{project}/deployments after uploading the ZIP.
Read deployments and logs before reporting completion.

Do not

Do not report success after a failed upload or deployment.
Do not guess the output directory if the user gave a specific path.
Do not expose tokens in commits, public logs, or screenshots.
Do not bypass the documented API contract.