Documentation

Track follow-ups, review drafts, and record confirmed sends from your own tools. Respawned supports job applications, sales, and other record types through one workflow.

An agent or person prepares a draft. A person approves it to the unsent outbox. A sending integration delivers the approved text and records the confirmed receipt. The browser, CLI, and Python SDK share one API; the engine owns policy, validation, and stored state.

Agent integration · Agent prompt · API reference

Install and start locally

You need curl, a POSIX shell, Python 3.12+ with venv and ensurepip, and a PostgreSQL database. The installer supports Linux, macOS, and WSL; release qualification runs on Linux.

curl -fsS https://respawned.williamshayden.com/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

The package includes the CLI, API, SDK, and prebuilt browser UI. View the installer or see installation options.

Configure PostgreSQL

On the engine host, create a PostgreSQL database and role, then set their actual connection values:

export DB_HOST=127.0.0.1
export DB_PORT=5432
export DB_NAME=respawned
export DB_USER=respawned
export DB_PASSWORD='your-database-password'
respawned ui

The engine initializes its schema and checks database and policy readiness. The launcher reports readiness and opens http://127.0.0.1:8000 with browser access connected. Leave it running while using the app. Startup creates no sample records and needs no model credentials.

Import source records

Start with one real record. Open Setup → Records & sources, paste a payload or choose a JSON file, and select Import records. Replace the example identity, date, and recipient below with confirmed source facts. No workspace or model setup is required.

{
  "opportunities": [{
    "id": "ats:application-123",
    "kind": "job_application",
    "title": "Backend Engineer at Example",
    "status": "open",
    "created_at": "2026-09-01T15:00:00Z",
    "contact_key": "ats:recruiter-22",
    "contact_name": "Alex",
    "contact_email": "alex@example.com",
    "preferred_channel": "email"
  }],
  "activities": []
}

Use Review imported records to open the queue, then open your record. Import saves facts; eligibility still depends on the server's policy. All tracked shows waiting records and their reasons. A record without a confirmed human recipient remains trackable but cannot become an outreach candidate.

Save the same payload as records.json for CLI use. The record contract covers activities and additional fields. Import accepts up to 1,000 combined items within 2,000,000 bytes. Larger declared or streamed HTTP bodies return 413 before JSON parsing. Records are complete snapshots, so omitted optional fields are cleared. Activities are immutable: exact replay is accepted and conflicting content rolls back the batch.

The server searches, filters by channel and view, and sorts before paging records. Tracked and ready counts cover the selected workspace; the result total reflects active filters. The inbox can load additional reply-contact pages. Activity orders events from the records loaded so far, with up to 100 recent events per record; Load more activity adds record pages to that subset.

Review and outbox

Inspect the record's reason, facts, and history. Choose Write draft, enter your own text, and select Save draft. Replace this example with your actual message; CLI users can save it as draft.txt:

Hi Alex, I am following up on my application for the Backend Engineer role at Example. Is there an update you can share?

A person then checks the saved text, recipient, and current saved facts and chooses Approve to outbox. Saving and approval are separate actions. The server rechecks the displayed version, current eligibility, recipient, and contact-wide cooldown before approval. Changed source facts invalidate an old review token even when copy is unchanged. Reopen the draft for fresh review.

Draft preparation context can be current, changed, or unknown. Fresh human review can approve eligible older copy, while automatic processing requires known matching preparation context. Final checks use fresh server time after model calls and review-lock waits. See the review contract.

The approved message appears in Outbox, still unsent. Refresh reads current engine state; it does not fetch source updates, draft, or send.

For a spreadsheet, download CSV in Outbox or run respawned outbox --path outbox.csv. JSON preserves exact text; CSV protects formula-like cells. Reading or exporting does not change status.

CLI and agents

The local launcher creates private CLI access for other terminals on that machine. Workflow clients do not need database settings or token copying. Optionally run respawned status from the client terminal to check engine readiness.

An agent prepares the record and draft:

respawned import --file records.json
respawned draft ats:application-123 --body-file draft.txt

The successful response identifies the saved draft and its status. No extra read or queue evaluation is needed to report that it was saved. Supplied text needs no engine model.

A person reviews that saved draft:

respawned review ats:application-123

Review opens the current saved draft and its source context, then prompts for a human decision. This selected-record mode does not generate copy or evaluate the queue. The 2.3 CLI requires the engine's review_context capability; older responses remain readable with upgrade guidance and no review writes. A successful edit is followed by a fresh draft read before another decision.

The agent guide covers SDK and HTTP alternatives, remote connections, and uncertain-write recovery. Download the prompt to give an agent the workflow and boundaries.

Connect a sending integration

Your sender reads approved messages from GET /v1/outbox/pending, delivers the exact approved text through its provider, then posts a confirmed result to POST /v1/outbox/{id}/receipt. The outbox status and related outbound history update together.

Use the dedicated RESPAWNED_OUTBOX_TOKEN, which grants neither drafting nor approval authority. Coordinate one logical sender per engine and use durable state and provider idempotency. Reconcile uncertain sends with the provider before trying again.

Outbox API reference · Download Python client

The standalone client needs Python 3.12+ and no third-party packages. It reads RESPAWNED_API_URL and RESPAWNED_OUTBOX_TOKEN from the environment.

Other CLI workflows

respawned inbox --json reads unanswered human replies. outbox --pending --json reads approved exact text. Bare review evaluates a bounded queue and prompts for human decisions, generating text when a draft is missing. sync --dry-run previews eligibility; process --limit 10 explicitly processes a batch under server policy, which defaults to human review.

These workflows use stored source facts. Your source connector owns refresh and scheduling.

Create and monitor workspaces

Workspaces are optional saved views. Choose Workspaces → New workspace, enter a name and record types, then save. Include all covers every current and future type. Add a record type prepares a view before importing it.

Use matching lowercase kind identifiers such as job_application, partnership, or project. Workspaces share engine policy, contacts, model settings, credentials, and outbox. Removing a workspace removes its view, not its data.

Overview → Choose workspaces selects several views to monitor, including views on other engines. Checks run every 30 seconds while visible and can be paused. Failures retain marked stale counts. Counts can overlap between views.

Configure a drafting backend

An engine model is needed only for Generate draft or a CLI draft request without supplied text. Write draft, agent-supplied text, review of saved drafts, and processing an empty queue or existing copy require no engine model.

Under Setup → Model backend, choose an OpenAI-compatible API or the optional Codex CLI adapter. Saved settings apply to requests from the browser, CLI, and API.

For an API backend, enter its URL, model name, timeout, and credential environment variable. Set the secret in RESPAWNED_MODEL_API_KEY or LITELLM_MASTER_KEY on the server and restart. The browser stores the variable name, not the secret. LiteLLM is optional.

For Codex, install and authenticate the runtime on the engine host, select codex_cli, and generate a draft to invoke it. Saving settings does not run login or availability probes. The engine validates accepted text and keeps all review checks.

Set the server policy's sender/sign-off before generating copy. Configuration saves do not call the backend.

Engine configuration

Engine commands do not automatically read .env. Keep DB_* values and model credentials in the engine's shell or service configuration. For a custom policy, set RESPAWNED_POLICY_PATH to a file outside the installation directory. respawned init is an optional explicit database/schema check before startup.

Use respawned ui --port 8001 for another port or --no-open to print the browser link. Set RESPAWNED_API_URL to that loopback URL in CLI terminals using a custom port. Stop a foreground engine with Ctrl+C; PostgreSQL remains separate.

PostgreSQL holds records, activities, drafts, outbox reservations and receipts, workspaces, and saved model settings. Preserve the engine environment and any custom policy file separately from database backups.

Access and draft version tokens

The one-use local browser link lasts five minutes. Its session lasts up to 12 hours, until Lock access, or until server shutdown. Private CLI access is separate and ends when its server stops.

Local browser sessions require both an HttpOnly cookie and a proof stored only in that engine origin's local storage. The UI sends X-Respawned-Session-Proof on every session read and write. The server stores only its hash and never returns a proof from a cookie-only request. Neither credential authenticates alone. Locking clears the proof and revokes the session; expiry or server shutdown also invalidates access. Local proof is never forwarded to another engine.

For remote access, configure RESPAWNED_REVIEW_TOKEN on the engine and restart. Enter it under Setup → Engine access or provide it in the client environment. Manual browser credentials clear on reload.

Operator credentials can process batches. A separate processing token is needed only when the caller should have that narrower permission. Outbox credentials do not grant drafting, processing, or approval.

Connect another engine

Run the other engine with its own database and operator token, behind HTTPS or a loopback tunnel. Configure RESPAWNED_UI_ORIGINS on that engine to allow the browser application's exact origin:

RESPAWNED_UI_ORIGINS=http://127.0.0.1:8000

Connections → Prepare a remote engine shows the correct origin. Comma-separate multiple origins; omit paths, trailing slashes, and wildcards.

In Connections, enter the engine name, API root URL, and access token, then choose Connect engine. Select its views in Overview or use Open engine. Manual tokens stay in tab memory; names, URLs, and watch choices persist.

Remote URLs require HTTPS; loopback HTTP is allowed. Browser requests carry only the selected engine's credential. The origin allowlist permits the browser connection; it does not replace authentication.

API reference and troubleshooting

The API reference covers routes, payloads, errors, and retries. The running engine serves schemas at /docs and /openapi.json. Use respawned serve --api-only for an engine without the bundled interface.

respawned status reads public health and readiness endpoints without an access credential. /healthz reports the engine version and process liveness. /readyz checks database, schema, and policy; it does not test a model. The status client needs no database settings.

Status accepts minor and patch differences within a major version. That reports version policy, not support for every workflow capability; the current CLI's interactive review requires the 2.3 coherent review-context response.

Installation options

To inspect the installer before running it:

curl -fsS https://respawned.williamshayden.com/install.sh -o install.sh
# Read install.sh, then run it.
sh install.sh

The installer verifies the wheel checksum, installs into ~/.local/share/respawned/2.3.0, and adds ~/.local/bin/respawned. Use sh install.sh --prefix /absolute/path for another prefix. No repository clone or Node.js is needed.

Download package · Source archive · Checksums · Package provenance · Site manifest · GitHub release

Update the engine and clients

Upgrading to 2.3

1. Stop the engine before upgrading; use Ctrl+C for a foreground ui or serve process. Keep PostgreSQL running for backup.
2. Back up the existing database and preserve the engine environment and any custom policy file.
3. Download the current website installer again and run it with the same prefix, following Install and start locally. A previously downloaded installer remains pinned to its original release. If you installed the wheel directly, update the 2.3.0 wheel in that same Python environment.
4. Restart with the usual ui or serve command and existing database settings. Check readiness, then reload the browser and reconnect clients. Separately installed clients can use respawned status to check the running engine.

Use matching 2.3.0 client and engine installations for this release. Update separately installed client environments with the engine; the matching browser UI is bundled with it. Reconnect local browsers with a fresh launch link so they receive the origin-scoped session proof.

The schema records draft preparation and accepted-review context. Older drafts with unknown preparation context remain available for fresh human review when eligible, but automatic processing cannot approve them without matching preparation context. Existing approved reservations and receipts are preserved. See 2.3 upgrade details.

The installer retains earlier version environments and has no uninstall command. To remove an installer-managed copy, stop the engine and remove its bin/respawned symlink and share/respawned program directory under the chosen prefix, after confirming they belong to this installation. Preserve PostgreSQL, its backups, and external configuration when removing program files.

Upgrading to 2.2

Version 2.2 introduced targeted review of a saved draft and the supplied-text first browser workflow. These remain available in 2.3 with current-context checks. Historical 2.2.0 package, source archive, and GitHub release links are retained with earlier release archives.

Upgrading to 2.0

When upgrading from 1.1 or earlier, workflow CLI commands move to the API. Remove database settings from client-only environments, and configure remote clients with the engine URL and credential. --now and --policy are server/simulation concerns, not workflow-client options.

Data routes require authentication starting with 2.0. New clients use /v1/workflow; existing /v1/ui aliases remain available. See the migration reference.