Deploy and run your app, task by task

For people who deploy and run apps on PitchStation: getting access, a first deploy with an AI assistant or the Apps client, then addresses, access, settings, monitoring, recovery and data. One section explains what the people you share an app with will see.

How to read this manual. ps-apps means ~/.pitchstation/ps-apps, the client launcher you set up in §02. Commands run from a work folder outside your project, ~/.pitchstation/demo-crm/ in the examples, and --source points at the project. Labels in bold are exactly as on the Apps page. The examples use one fictional app, demo-crm (id 41).

§01Before you start

Know what Apps is, whether you can use it, which hosts and limits apply, how your token is kept, and which way in suits you.

What Apps is

Apps runs a project in Docker on a host PitchStation manages. It takes a project with a Compose file, or a Vite + React or Next.js (standalone) project. A Compose file (compose.yaml) lists the containers your app runs as, called services; for a Vite or Next.js project the Apps client writes one for you (see §16 Glossary).

The host builds your images, so a first deploy needs no Docker on your computer. You need Docker only to build image archives yourself (§04).

• Your app gets an HTTPS address, demo-crm.apps-ap.pitchstation.ai or demo-crm.apps.pitchstation.ai depending on its host, or your own domain.
• Access is public, or private with a password you keep. An expiry is optional.
• Every deploy is a numbered release. A readiness check proves the address serves your app.
• Changing an address or the access never rebuilds or restarts the app.

The overview has the short version: What you get.

Who can use it

An administrator turns Apps on per person, with the permission “Deploy hosted apps (containers)” (app.deploy). It is in no role preset, and signing up does not include it; administrators have it. With it, Apps appears in the sidebar between Dev instances and Documents.

Without it, /apps.html still opens, but every panel answers CAPABILITY_REQUIRED: You do not have permission to use this feature. If you are not signed in, the message reads 401: Authentication required. Please provide a valid token. and the page does not send you to sign in.

123

1. Dev instances — the sidebar has no Apps item below it yet.
2. CAPABILITY_REQUIRED: You do not have permission to use this feature. — the status message, where every panel reports.
3. Hosts and spend are unavailable: … — the hosts panel cannot load without the permission either.

Hosts and your quota

Shared hosts. Several people's apps share them, and the Compose rules and per-app budgets are enforced there. You can have 3 apps on shared hosts unless an administrator sets another number (0–100) for you.

Your own isolated host. You reserve it and an administrator launches it. Nobody else's apps run on it, and its apps do not count against the quota. See §14.

The two platform regions. Platform hosts in Singapore run ARM64, with addresses under apps-ap.pitchstation.ai. Platform hosts in Oregon run x86, with addresses under apps.pitchstation.ai. Which hosts you may use changes over time: ps-apps targets lists them, with free slots, free memory, CPU type, region and your quota. The overview keeps the status in this release.

Each app gets a default budget of 512 MB memory, 1 CPU and 256 processes.

Your token, and where it lives

Make a token at /tokens.html: under Access, choose the Apps preset (scopes apps:read, apps:deploy and account:read). You need the permission first; until then the preset is marked not available.

The token starts with pst_ and is shown once. Choose an expiry (30, 90 or 365 days are offered). Keep Server only on: it refuses requests that carry a browser Origin header. An IP allowlist of up to 20 addresses is optional.

Keep the token in ~/.pitchstation/.env, readable only by you (§02 shows how, in your own terminal). Never paste it into a chat, and keep it off command lines: the client refuses --token. The one documented exception is the quick MCP registration, which stores the token in your assistant's settings; §02 also gives a way that keeps it in your file.

Publisher terms, if your platform requires them

The terms appear only when an administrator setting requires them. Until you accept the current version, creating apps, live deploys, and quoting or reserving an isolated host answer TERMS_REQUIRED. Deploy dry runs still work.

Accept them on the Apps page with I accept these terms while signed in. ps-apps terms only shows them. Your assistant must never accept them for you.

12

1. PitchStation Apps — publisher terms (version …) — the version and text you are accepting.
2. I accept these terms — records your acceptance of this version.

Ways in, and which to pick

The MCP tools stop at deploy and status because domain, access and env changes are reviewed plans: a conversation, not one tool call. The overview explains the channels: Ways in. Setting each one up is in the deploy guide's Set up once, and the REST conventions are in the API reference.

§02Quick start

Get one app live through the route you prefer, then see what to do next on the web page. Every route needs the permission and a token (§01). Choose private or public before you create the app; the deploy guide's app contract says how to shape the project.

With an AI assistant that runs commands (Claude Code, Codex)

The assistant follows the PitchStation Apps skill: it prepares the project, shows you each dry run and deploys only what you asked for.

This rewrites the whole file and makes it readable by you alone, even if an older setup left it readable by others. If you run it again for a new token, add the MCP server's line again afterwards (see the MCP route below).

Codex reads the same file from ~/.codex/skills/create-pitchstation-app/SKILL.md.

With an assistant without a shell (MCP)

To keep the token in your own file instead, add it for the MCP server once, then register with a command that loads the file each time the assistant starts the server:

Codex takes the same with codex mcp add.

With the Apps client

The Apps client is one Node file (Node 20 or newer, no dependencies). Its output is JSON, so it suits terminals and CI.

Optional fields: "migrateCmd", "env": {…}, "resources": {"memMb": 768, "cpus": 1, "pids": 256}, "placement": {"arch": "amd64"}, and the deploy settings "migrateService", "hooks" and "composeFile" (§08). Leave out targetId and the platform places the app.

Then, on the web page

• Open Apps in the sidebar, or go to pitchstation.ai/apps.html, and choose your app in Application.
• Press Check readiness, then Copy redacted receipt (§09).
• Next: a custom domain (§05), access links for named people (§06), backups (§13), status and logs (§09).

The deploy guide covers the same ground for each channel: Set up once, Create the app, Deploy a release and declaring a public app.

§03The Apps web page, panel by panel

Know what every panel is for, when it appears, and where its task is explained.

Opening the page

Choose Apps in the sidebar, or open pitchstation.ai/apps.html; on a phone, open the menu first. /apps.html#app=41 opens one app directly. The page lists only your own apps, newest first; administrators also see only their own here.

The screenshots in this manual come from an example account: every name, address and value in them is fictional.

123

1. Apps — the sidebar item; it appears once you have the permission.
2. Status message — where every panel reports its result or error.
3. Your hosts and spend — your spend cap, isolated hosts and what each app costs (§14).

Where results and errors appear

Every panel reports in the single status message at the top of the page, which may be far from the button you pressed: after a click, look up. Errors show the code and a sentence; §11 explains each code.

How changes move through the page

Most changes are previewed first (Review …, Quote, Preview), then made with Apply selected plan, Apply, Apply budget, Move, Reserve, or Save in Deploy settings.

These act at once, with no preview: Save backup settings, Back up now, Create link, Save under Read-only file system, Retry safe steps and Request cancellation. These ask first, then act: Revoke (links), Remove (image archives), Cancel and Release (hosts).

The page makes its own idempotency keys, so applying the same plan twice returns the same operation.

The panels

• Refresh in Current state reloads the configuration, plans, readiness and operations only. To reload links, backups, moves, settings and archives, reload the page: the address keeps #app=41, so the same app opens again.
• Status and logs load only when you press their buttons.
• Panels 5–18 appear only when the platform's publishing switch is on. If none appear after you choose an app, read the status message and ask an administrator. An app from before managed publishing shows Inventory required and needs an administrator first.

The notices read like this. Takedown: “An administrator took this app down on … It serves 404 and cannot be changed until the takedown is lifted.” Move: “Moving to host … Changes wait until the move finishes.” Build-time settings: “Build-time settings changed since this release was built (…). The running app still uses the old values until you deploy again.”

What the page does not do

The same tasks by client, MCP and REST are in the deploy guide's Operate table and the endpoint list.

§04Deploy and redeploy

Ship a release safely, repeat it safely, and know what the platform does with your files and images.

The rhythm: dry run, review, apply, follow

Every channel follows the same rhythm. The dry run deploys nothing and changes nothing on the host; it returns the plan and the exact file list. With an image archive (--image-archive, or MCP's image_archive) the archive itself is uploaded and kept: it appears under Image archives, and it can push an older one out of the newest three the platform keeps. The apply returns an operation id at once, and the release is live only when the operation reports succeeded. Closing your terminal or laptop does not stop the operation.

• Apps client: a dry run, then the same command with --apply --key … --watch, then operation … --watch if needed (§02).
• Assistant: “Redeploy to PitchStation, show me the dry run first.”
• MCP: the deploy request in §02.
• Web page: not possible; the page does not upload code.

Idempotency keys

A key names one intent: 8–128 letters, digits, dots, underscores or hyphens, for example release-20261002-01.

• Same key, same request: you get the same operation back (duplicate: true). Nothing runs twice.
• Same key, different request (for example, the source changed): IDEMPOTENCY_KEY_REUSED.
• After a transport error, repeat the identical command with the same key.
• After a failure, the same key only returns the failed operation. Deploy the fix with a new key.
• The web page makes its own keys.

Releases

Every deploy creates a numbered release. ps-apps releases --app 41 lists the app's 20 most recent releases: each one's id (what --release takes), when it was created, its status (pending while its deploy runs, then live, superseded or failed) and whether it is the live one. ps-apps list shows each app's currentRelease.

Data on named volumes survives every release; anything written inside the image is lost. A rollback brings back an earlier release's Compose file, not its env or settings, and its code only when each release's images carry their own tag: see §10 Roll back before you rely on it.

What a deploy does, and where it can stop

Before the first step, an operation that touches routing (deploys included) checks DNS and the TXT proof of every name the app has. A missing record makes it wait in waiting_external (§05, Keep the TXT record).

The steps run in this order: preflight, upload (and upload images), write env, Compose check, budget, build or load images, backup, copy of the backup to the platform, pre-deploy hooks, migration, up, health check, post-deploy hooks, activate, then routing and certificates, and readiness.

• The backup runs only when backups are set up and the app already had a release. Copying it to the platform (backup-pull) only warns if it fails.
• Pre-deploy hooks and the migration each run in a new one-off container of their service, from the new release's images (docker compose run --rm), before up replaces the running containers. Post-deploy hooks run the same way, after the health check.
• Time limits: build 20 minutes, migration 15, up 10, health 5; any single remote step 30.
• Failures before up (upload, build or image load, pre-deploy hooks, migration) leave the previous release serving. From up on, the new containers have replaced the old ones on the same port.
• A failure after the build or image load (the backup, a pre-deploy hook, the migration) has already replaced the host's images for the services it builds, under the same names, unless each release tags its images differently (§10, Roll back). The next env change, or a rollback to the release that is serving, then starts that build. Deploy a fix before either.

The health check. healthPath must return exactly 200 within about 60 seconds: 30 tries, 2 seconds apart, 5 seconds each. A redirect counts as a failure. A failed check's output starts unhealthy — last code: NNN and ends with the containers' last 40 log lines. A code of zeros (000 or 000000) means nothing answered at all (§12, The deploy fails its health check).

What gets packaged

ps-apps package shows exactly what would be uploaded, without any network call. Anything else in the project folder is uploaded, which is why input files and image archives belong in your work folder (§02).

The client gives the deploy upload up to 15 minutes and an image archive upload up to 60; every other call gives up after 30 seconds. On a slow connection, keep the bundle small, or build elsewhere and deploy an image archive.

Projects the client can package

Generated files go into the upload only; your project is not rewritten. Another kind of project fails with ADAPTER_UNSUPPORTED: add a Compose file.

Shared and strict hosts refuse privileged containers, host namespaces, the Docker socket, bind mounts outside the project and ports not on 127.0.0.1; §15 has the full list, and the deploy guide shows them with a scaffold in Deploy a release. Shape the app to the app contract: listen on 0.0.0.0 inside the container, keep data on a named volume, give it an unauthenticated health endpoint, and make the migration safe to repeat.

Build elsewhere: image archives

Build the images on your machine, in CI or on a Devbox and deploy them: the host loads them and builds nothing. The platform keeps your newest 3 archives plus the one the running release came from, up to 1,024 MB each.

• Every service with build: needs image: name:tag: images are loaded by tag. Use a tag that changes with each release, so a rollback can find the older images (§10).
• The images must match your app's host CPU: --platform linux/arm64 or linux/amd64, whichever ps-apps targets shows for it. The shared hosts are fixed per host; an isolated host can be either type in either region. The dry run refuses a mismatch with IMAGE_ARCH_MISMATCH.
• deploy --image-archive uploads the archive once; the same file is not sent again. ps-apps images --app 41 lists the archives, --file uploads one and --remove ARCHIVE_ID removes one.
• With MCP, pitchstation_app_deploy takes image_archive, an absolute path.
• On the web page, Image archives lists and removes them. You cannot remove the archive the running release came from.

If the client reports that “the server's edge refused” a large upload before PitchStation saw it, make the archive smaller or ask an administrator.

123

1. Archive — the first 12 characters of the archive's id, its SHA-256. ps-apps images --app 41 lists the full id, which --remove takes.
2. Images — each image's tag and CPU type.
3. Remove — removes an archive you no longer deploy from; deploying from it again needs a new upload.

Build on a Devbox

If you use PitchStation dev instances (the pitchstation-devbox skill; see Dev instances), one command builds an archive on the box for your app's host CPU and deploys it. The skill installs devbox.py in ~/.claude/skills/pitchstation-devbox/. Your token reaches the box on the SSH session's input, never on a command line or its disk.

• It builds the project in ~/work/BOX on the box unless you pass --box-path.
• Without --apply it uploads the archive and returns the deploy's dry-run plan. With --apply and no --key it makes a key of its own, then follows the operation for up to five minutes and prints where it ended; follow a longer one with ps-apps operation … --watch.
• The box needs Docker with Compose, Node 20 or newer, and image: tags on built services.
• It takes the Apps token from the environment or from ~/.pitchstation/.env, where §02 saved it.

The build ceiling

Builds on a host run one at a time, inside a ceiling — needs host setup. It defaults to 40% of the host's memory (at least 1,024 MB) and 1 CPU, unless an administrator set the host's own. A build that hits it fails with BUILD_LIMIT_EXCEEDED, and nothing else changes. Build elsewhere (an image archive or a Devbox) or make the build lighter.

An administrator installs the ceiling when onboarding a host. On a host without it, builds are not capped, and the 20-minute build limit still applies.

Redeploy

Run the same command with a new key. A redeploy keeps domains, access, env and the budget.

• Pass the same --marker on every deploy, as the client advises. If you leave it out, the stored marker and critical assets are kept (a Vite project sends its own marker each time). A deploy that carries a marker replaces both: the critical assets become none (§05, Identity marker).
• A redeploy never drops a private app's password. Leave --password-file off: on a redeploy it sets the password again and signs everyone out (§06).

More detail for each channel is in the deploy guide: Deploy a release, What gets packaged, image archives and deploy settings. The API conventions are in Conventions and Operations.

§05Addresses and custom domains

Know your platform address, put the app on your own domain, manage aliases, and keep the ownership proof in place.

Your platform address

Every app gets its slug plus its host's base domain:

• Singapore's shared hosts: demo-crm.apps-ap.pitchstation.ai
• Oregon's hosts: demo-crm.apps.pitchstation.ai
• An isolated host without per-app DNS: the host's own label in between, for example demo-crm.h7.apps-ap.pitchstation.ai

The address is reserved when the app is created, and the slug is fixed. In 1 · Domains, Platform address offers Keep serving with the same policy, 308 redirect to primary and Disable (404); in domains.json these are retain, redirect and disabled. While the platform address is the primary hostname, it must keep serving.

Put the app on your own domain

On the web page it takes five steps. The figures follow the steps, in the same order. They show a second name, www.crm.example.com, being added to an app that already serves crm.example.com; a first custom domain works the same way.

123456

1. Primary hostname — the main address; redirects point here.
2. Aliases (one per line; new aliases redirect) — more names for the app.
3. Platform address — keep serving, redirect to the primary, or disable.
4. Expected page identity (unique text, at least 12 characters) — the marker readiness looks for (§05, Identity marker).
5. Critical assets (one path per line) — paths that must answer with real content.
6. Review domain plan — saves a plan; nothing changes yet.

12345

1. TXT _pitchstation.www.crm.example.com — proves the name is yours. Keep it.
2. A www.crm.example.com — sends visitors to the host's address.
3. Copy record — copies the record as one line: name, TTL, class, type and value.
4. The platform address — PitchStation manages its DNS; add nothing for it. On a host registered with its own base domain, the note says the address resolves through that base domain's own DNS; add nothing for it either.
5. Records of verified hostnames: keep them at your provider — the records of names already proven; deleting one stalls later deploys.

1234

1. Saved plans — your reviewed plans, with their expiry.
2. Plan preview — what the plan changes, before anything happens.
3. Verify DNS and ownership — checks the records from three resolvers; it does not touch the app.
4. Apply selected plan — starts the operation.

With the Apps client. Plan the domains, add the records, verify, apply, then check readiness. The plan's output prints its id and etag for the apply; keep the ETag's double quotes inside single quotes. If more than 15 minutes pass before you apply, plan again (the TXT value stays the same) and use the new id and etag. ps-apps show --app 41 also lists the records, under dnsRecords.

Add the records it lists at your DNS provider, then verify with the plan's id:

With an assistant: “Put demo-crm on crm.example.com. Give me the DNS records to add, and apply once I say they are in place.” Or: “Connect crm.example.com to this app. Keep its password and expiry; do not rebuild it.” With MCP this is read-only: pitchstation_app_status lists the pending records.

A TTL of 300 seconds is suggested.

Aliases, detaching and limits

• An alias either serves the app or redirects with 308 to the primary, keeping the path and query. On the page, new aliases redirect; in JSON, a plain name means redirect.
• Names you leave out of a new plan stay attached, as serving aliases. To remove one, add "detach": ["old.example.com"] to domains.json; the web form cannot detach.
• An app has at most 10 names, counting the platform address: 9 aliases when the platform address is the primary, 8 with a custom primary.
• Names under pitchstation.ai, pitchstation.com and other apps' platform addresses are refused.
• A name held by another app or a PitchStation website answers DOMAIN_ALREADY_BOUND. An unverified claim lapses after 24 hours.

Keep the TXT record

Identity marker and critical assets

Readiness proves that the address serves this app. It needs a marker: 12–256 characters your home page's HTML always contains, for example the text of its page title. Readiness reads the HTML as served and runs no scripts, so text that JavaScript draws does not count. Vite apps get one automatically. For other projects, pass --marker on every deploy, marker with MCP, or set Expected page identity in 1 · Domains.

Critical assets are up to 16 paths, one per line, that must answer 200 with real content. On the page they are sent only together with Expected page identity, so fill both.

The deploy guide covers addresses in Addresses and access, and the ETag rules are in the API reference's Conventions.

§06Who can open your app

Choose public or private, manage the password and expiry, give named people their own way in, and open the paths machines need.

Public or private

• New apps are public, with Separate application login or expiry set to Unknown, unless you chose at creation.
• Private needs a password of 12–72 bytes that you keep. PitchStation stores only a hash and cannot show it again.
• Switching to public deletes the stored password; going private again needs a new one.
• To be private from the very first request, create the app with --private --password-file (§02), pass --password-file on the first deploy, or password_file with MCP. Do not deploy publicly and add the gate later.
• Leave --password-file off later deploys: each one sets the password again and signs everyone out.

Change access, password or expiry

On the web page, fill 2 · Access and expiry, press Review policy plan, then Apply selected plan in 3 · Review and apply. Passwords are never saved in the browser or in receipts. If the app lets people sign in with PitchStation, making it public turns that off; the message says so when you review.

1234567

1. Platform access — Public or Private preview.
2. New preview password (12–72 bytes; empty retains existing) — only when you mean to change it.
3. I retained the new password for a separate, secure handoff. — the page will not send a password without it.
4. Expiry (your local timezone; empty means permanent) — when every address closes.
5. Event date (optional, your local timezone) — for your records.
6. Separate application login or expiry — what your app restricts by itself.
7. Review policy plan — saves a plan to apply in 3 · Review and apply.

With the Apps client, the password goes inside an owner-only policy.json; policy has no --password-file.

Check the plan, then apply it with its id and etag:

"accounts": null turns off Sign in with PitchStation, which a public app cannot keep: without it, an app with people or teams listed answers POLICY_INVALID (field accounts). The web page clears the list for you.

With an assistant: “Make demo-crm public; it has no login of its own.” or “Make demo-crm private again with a new password file.” Neither change rebuilds or restarts the app.

Access links for one person

An access link opens a private app for one named person without the password: https://crm.example.com/__ps/enter?t=…. Its expiry is optional, within 366 days, and an app can have up to 50 active links.

• Creating or revoking a link re-applies the app's routing. The link works, or stops with its sessions, once that operation succeeds.
• A link gives its person a session of up to 12 hours, never past the expiry; opening the link again starts a new one.
• Changing the password ends link sessions, but the link itself keeps working; revoke it to stop it.

1234567

1. For whom — a label you will recognise, for example “Priya (design review)”.
2. Expires (optional, your local timezone) — when the link stops working.
3. Create link — creates it at once.
4. Opened — how often the link was opened and when it was last used — needs host setup.
5. Copy link — “Link for … copied. Send it only to them.”
6. Revoke — asks “Revoke the link for …? Their session ends too.”
7. revoked — a revoked link stays listed with its state.

Sign in with PitchStation

On a private app, list People (up to 50 usernames) and Teams (up to 20, by handle or @owner/handle, teams you can see). They can then open the app with their PitchStation account; you always can.

• Membership is checked at each sign-in. Removing someone takes effect when their session ends, at most 12 hours later. Clearing the list ends every account session at once.
• Only people can sign in, not service accounts. Unknown names are refused at review (POLICY_INVALID), and the message names them (“Unknown username: …”).
• New sign-ins need PitchStation to be reachable.

On the web page, fill the fields, press Review plan, then Apply. The message reads “Applying (operation …). The change is live once the operation succeeds.” Applying re-applies routing: no rebuild, no restart.

1234567

1. Callback paths (up to five, each /like/this/) — served without the password (§06, Callback paths).
2. Cache paths (up to five) — files a viewer's browser may keep.
3. People (PitchStation usernames) — who may sign in with their account.
4. Teams (handle or @owner/handle) — teams whose members may sign in.
5. Review plan — shows the change; nothing happens yet.
6. Apply — starts the operation.
7. Sign-in: morgan, priya, team sales — the reviewed list.

With the client, plan and apply this file as above.

Callback paths for webhooks and OAuth

Up to five path prefixes on a private app are served without the password, for signed machine callbacks such as payment webhooks and OAuth redirects. Each starts and ends with /, for example /api/payments/webhook/; it cannot be / or under /__ps/. Matching is by prefix, so /api/payments/webhook/stripe is covered but /api/payments/webhook is not. The expiry still applies.

Cache paths

A private app is no-store by default. Responses under a cache path, or ones your app marks immutable, may stay in the signed-in viewer's own browser for a year (private, max-age=31536000, immutable). Revoking someone does not remove files already cached on their device, so use this for content-hashed files only.

Expiry and event date

The expiry closes the app on every address and every path, callback paths included: every request answers 410, a plain “410 Gone” page from the host. On a private app, the sign-in page and access links say “This app is no longer available.” The expiry is checked on each request on the host, so it holds even when PitchStation is unreachable. Access links stop too, and readiness reports PUBLICATION_EXPIRED.

Set it when you create the app with ps-apps create … --expires 2026-11-15T23:59:00+08:00, or later in 2 · Access and expiry or a policy plan. Renew it with a later date, or remove it: no rebuild, no restart. Dates need a timezone; the page uses your local time. The event date is for your records and only warns when the expiry comes first. The deploy guide covers the same in Addresses and access, Access links and Private apps.

§07What your visitors see

What the people you share an app with meet, and what to send them. You can send a teammate a link to this section.

• Public app: visitors open the address. If the app has its own login, they see that.
• Private app: browsers see a small page, This app is private: “Enter the password you were given, or open the access link you received.” It has a Password field and an Open button, and Sign in with PitchStation when you listed people or teams. A correct password gives a 12-hour session, never past the expiry. A wrong one shows “That password is not right.” After ten wrong tries in ten minutes from one address: “Too many attempts. Wait ten minutes and try again.”
• Access link: it opens the app straight away for that person, with a session of up to 12 hours. The link itself works again until it is revoked or expires.
• Sign in with PitchStation: visitors who are not signed in to PitchStation sign in first, then come back with a five-minute pass. People not on the list see Not on the list: “Your PitchStation account is not on this app's list. Ask the person who shared the app to add you, or use the password or access link you were given.”
• Scripts and API clients use HTTP Basic with the user preview and the password.
• After sign-in, the visitor's own Authorization header reaches your app, so a bearer-token API works behind the gate.
• Private pages carry X-Robots-Tag: noindex, nofollow and are not cached, apart from cache paths and responses your app marks immutable (§06).
• Closed app: after the expiry, every address and path answers 410 Gone, a plain error page from the host; your app is not reached. On a private app, the sign-in page and access links say “This app is no longer available.” An app an administrator took down answers 404.

What to send people

• The address.
• The password, separately; or give each person their own access link.
• That a session lasts up to 12 hours.
• For teammates with PitchStation accounts you listed: they can use Sign in with PitchStation.

Report a problem with an app. Anyone can report one at pitchstation.ai/abuse.html, without an account. The reporter's email is never shared with the owner.

§08Settings and secrets

Set environment variables and build-time values, deploy settings and hooks, and read-only services, knowing what each change restarts.

Environment variables

Preview a change first: it lists which keys change and which stay. Applying restarts the current release with the new values, without a rebuild. Unrelated keys are kept, and if the restart fails, the previous env is restored.

Check which keys change and which stay, then apply. Applying restarts the app.

• Values are stored encrypted, and the API returns key names only.
• Values of 6 characters or more are masked in logs and step output as [redacted:KEY]. Shorter values and common words (production, true and so on) are not, so do not print secrets.
• The rules for names and sizes are in §15. PORT, HOST_PORT, COMPOSE_* and DOCKER_* are reserved.
• There is no env control on the web page or in MCP.

Before the first deploy. Until a release has gone live, applying an env change fails with CONFIG_REVIEW_REQUIRED, whose message mentions a legacy app. That also covers a first deploy that failed. Put the values in app.json under "env" when you create the app. If the app already exists, store them with REST: the call replaces the whole stored set, and the next deploy uses it.

The token travels to curl on its input (-H @-, curl 7.55 or newer), so it never appears in the list of running commands.

Build-time keys

Frameworks bake some values into the build: NEXT_PUBLIC_*, VITE_*, REACT_APP_*, NUXT_PUBLIC_*, EXPO_PUBLIC_*, GATSBY_* and PUBLIC_*. A restart cannot change them. The env preview lists such keys under buildScopedKeys with rebuildRequired: true; the app then shows a notice until a deploy succeeds. Redeploy to pick the new value up.

The platform writes the release's .env before it builds, so the file is part of the default build context. A framework that reads .env while it builds, as Vite and Next.js do, picks the values up. The client's Vite scaffold, and its Next.js scaffold for an app at the source root, work this way. A Next.js app in a workspace (--app-dir) does not: Next.js reads .env only from the app's own folder. An image archive is built on your machine with your local env: the platform's values never reach it, yet a deploy from it still clears the notice.

To mark other keys as build-time, or one of these as runtime, send scopes only; they are stored without a restart, but the client still wants --key with --apply.

Deploy settings: migration, hooks, Compose file

Preview the settings, then save them; saving needs no key. They apply from the next deploy, and an operation already accepted keeps the settings it was accepted with.

Check the settings as they will be, then save them.

• The migration and each hook run in a new one-off container of the named service (docker compose run --rm), not inside the running one. So localhost in a hook is that one-off container, not your running app: that is why the example warms the cache with a script.
• Commands are split into words the way sh does. Shell operators outside single quotes are refused (; | & < > ( ) $ and backticks); wrap such a command as sh -c '…'. A command is one line of up to 2,000 characters and 100 words, and is never shown back.
• Pre-deploy hooks (up to 5) run after the images exist and before the migration. A failure stops the deploy like a failed migration.
• Post-deploy hooks (up to 5) run after the health check and only warn.
• Each hook has a timeout of 1–1,800 seconds (default 300).
• Rollbacks and env changes run neither the migration nor the hooks.
• The deploy's dry run (not the settings preview) refuses a hook or migration in a service the Compose file does not define. A Compose file that uses include is not checked this way.
• composeFile is a relative .yaml or .yml path inside the project.

12345

1. Current settings — the migration service, hooks and Compose file in use.
2. Change (JSON; null clears a setting) — only the settings you change.
3. Preview — checks the change; nothing is saved yet.
4. Save — “Saved. The next deploy uses them.”
5. The preview — the settings as they will be.

Read-only services

The services you list (up to 16) run with a read-only root file system and a writable /tmp; keep data in named volumes. The change applies at the next deploy, rollback or env change. On the web page, Save stores the list at once, with no preview; it still takes effect at the next deploy, rollback or env change.

12

1. Services (comma separated) — the services to run read-only.
2. Save — stores the list.

What cannot change after creation

The slug, the web service, the container port and the health path are fixed, and so is the name on the Apps page. To change one, create a new app and move your domain to it: detach the name here, then plan it there. The deploy guide covers Environment variables, build-time keys and deploy settings, and the host rules are in Strict hosts, egress and acceptable use.

§09Watching your app

See whether the app is healthy, read its logs, size its budget, prove it is reachable, and know what is recorded.

Container status

On the web page, press Show container status. The table shows Service, State, Health, Restarts, Last exit (“(out of memory)” when the container was killed for memory), Memory, CPU and Started, with the budget line below it. In a terminal, run ps-apps status --app 41. With MCP, pitchstation_app_status also shows pending DNS records, the last 3 operations and readiness.

Status is cached for 15 seconds. Status and log reads together are limited to 10 a minute per person per app (RATE_LIMITED); a cached status answer does not count.

123456789

1. Show container status — reads the containers from the host.
2. Last exit and Memory — how each container last stopped, and what it uses now.
3. Budget: 768 MB, 1 CPU, 256 processes. — the budget, and whether the host enforces it.
4. Memory (MB, 64–16,384) — with CPUs and Processes, the new budget.
5. Review budget change — a preview; nothing changes yet.
6. Apply budget — enabled after a review.
7. Service — which service's logs to read; filled once you show the status.
8. Read logs — reads the latest lines.
9. [redacted:DATABASE_URL] — a masked value from your environment.

Logs

On the web page, press Show container status first, so Service lists your services. Then set Lines (1–1,000) and Since (for example 10m or 2h; empty for the latest lines) and press Read logs. With MCP, use pitchstation_app_logs.

A read returns up to 1,000 lines or 256 KiB. Lines from all services are interleaved by time, and values from your env are masked. Every read is recorded, including reads by administrators.

Resource budget

The default budget is 512 MB, 1 CPU and 256 processes. You can set 64–16,384 MB, 0.1–16 CPUs and 32–4,096 processes. On shared hosts the budget is enforced: an app over its memory is killed inside its own budget, never its neighbours'.

• On the web page, the budget fields show the app's stored budget as soon as you choose the app; a field you leave empty keeps its stored value. Set Memory, CPUs and Processes, press Review budget change (a preview that says whether the budget fits the host, or shows the host's warning when it would not), then Apply budget.
• On a host that enforces budgets, the message reads “Budget change accepted (operation …)”, and the change is live without a restart. On other hosts it reads “Budget 768 MB, 1 CPU, 256 processes. Stored and shown; this host does not enforce budgets yet.”
• RESOURCE_ADMISSION means the host has no room for that budget. The message gives the numbers, for example “Requested 4096 MB; 2304 of 3584 MB is already committed on the host, so at most 1280 MB fits.”
• On your own isolated host, budgets are stored and only warn, unless the platform is set to enforce them.

Check that the budget fits the host, then apply.

With an assistant: “Raise demo-crm's memory budget to 768 MB. Show me the preview first.”

Readiness: proof the address works

Press Check readiness, run ps-apps readiness --app 41, or use pitchstation_app_readiness. Every deploy, rollback and configuration operation also runs it at the end.

1234567

1. Verified ready (HTTP/TLS/policy/assets) — the headline (table below).
2. Desired revision 8; applied revision 8. — the configuration you asked for, and what the host runs; then access and expiry.
3. Refresh — reloads the configuration, plans, readiness and operations.
4. Check readiness — runs the checks now.
5. Copy redacted receipt — copies a summary without passwords.
6. crm.example.com · primary: applied … — each hostname's routing state.
7. crm.example.com: passed · certificate expires … — each hostname's readiness and certificate.

12

1. Not yet verified ready — no recent passing check (table below).
2. expiry: … — in your local time, then in UTC.

• A result is valid for five minutes. Check readiness within 30 seconds of the last check returns that result.
• The result goes stale when the configuration, the release or the app's running state changes.
• After a failed deploy, the headline stays Not yet verified ready until a deploy or rollback succeeds, even if the previous release still serves.

The deploy guide's checklist Before you announce it lists what to try by hand.

Receipt

Copy redacted receipt (“Copied. No passwords were included.”) or ps-apps receipt --app 41 gives the app id, URLs, policy summary, revisions, release, latest readiness and last operation id, never a password.

Access-link use

The Opened column of Access links shows how often each link was opened and when it was last used — needs host setup. The host reports this every five minutes, link ids and times only. On a host whose reporter has not been updated by onboarding, it keeps showing “not yet”.

What is recorded

The last 50 events of each app are in ps-apps show --app 41: plans, applies, operations, log reads, moves, backups, sign-ins with PitchStation and takedowns. Each event has its name, revision, operation id, who and when. The deploy guide's Operate table lists the same tasks by channel.

§10When something goes wrong

Follow an operation, retry or cancel it, resolve an uncertain one, roll back without falling into the health-check trap, and stop or delete an app.

A deploy failed: what to do first

Operations

Every applied change becomes an operation with an id: deploys, rollbacks, env, domains, access, links, budget, backups and restores. Operations run one at a time per app; while one is active, other changes answer OPERATION_BUSY.

States: queued, running, then succeeded, or failed or cancelled. An operation can also wait in waiting_external (usually for DNS) or be cancel_requested.

• On the web page, Operations and recovery lists the latest 30, newest first. Each shows its action and status (and its phase while it runs), when it was accepted and when it finished (for an operation you reconciled, when you reconciled it), its id and cleanup state, any error as “CODE — who: what to do”, and the numbered steps. A failed step's last lines open under “Output of STEP (last lines, secrets masked)” and are kept 30 days. The panel refreshes every 3 seconds while an operation is active.
• In a terminal, ps-apps operation … --watch follows an operation for up to 5 minutes; its exit code is 1 when the operation failed or was cancelled. With MCP, use pitchstation_app_operation.
• Find the operation id. The apply prints it ("operation":{"id":…}), ps-apps show --app 41 lists the app's recent operations, and the web panel shows it on each.
• Read a failed step from the terminal. Read the operation once, without --watch. Each step has a status, and a failed one an error whose output holds its last lines (about 60 lines or 8 KiB at most, secrets masked). cleanupState and reconcile say what comes next.

The error line names who acts by default, so “operator” also appears on failures you fix yourself, such as a failed health check. Read the step output first.

Retry

Retry safe steps, ps-apps retry or MCP's action: "retry" continue the same operation and skip the steps that already succeeded. Retry works for a failed or waiting operation whose error is retryable, that needs no reconciliation, and whose configuration has not changed since. Use it for passing causes: DNS now fixed, a host that was unreachable, a slow start. After a code or configuration fix, deploy again with a new key. TLS_RATE_LIMITED refuses retries for 60 minutes. On the web page, Retry safe steps appears only on a failed operation: one that waits in waiting_external tries again by itself, within about 15 minutes, and ps-apps retry tries it now.

123456

1. deploy: failed — the action and its status.
2. cleanup: artifacts_retained — nothing is uncertain; the release's files are kept.
3. STEP_FAILED — operator: … — the error line; read the output before you act on “operator”.
4. health: failed — STEP_FAILED — the step that stopped the deploy.
5. Output of health (last lines, secrets masked) — what the step printed.
6. Retry safe steps — runs the failed steps again; use it only for passing causes.

Cancel

Request cancellation, ps-apps cancel or MCP's action: "cancel" stops the operation at the next safe checkpoint. Afterwards, check status and readiness before you deploy again.

Resolve an uncertain outcome

Some failures leave the platform unsure what happened on the host:

• a migration or pre-deploy hook that exited non-zero;
• up or activate that failed, or an env restart whose previous env could not be restored;
• a failed restore;
• a step that timed out;
• a dropped connection.

An env restart that fails but restores the previous env is not uncertain: it reports ROUTE_APPLY_FAILED (§11), and the app runs as before.

The operation then shows “cleanup: reconciliation_required”, and every new change answers RECONCILIATION_REQUIRED until someone resolves it. Who resolves it is in the notice under the operation, and in reconcile.by when you read the operation in a terminal, not in the error line: that line reads “RECONCILIATION_REQUIRED — operator: …” even when you can resolve it yourself.

You resolve it when only your containers were involved: the migration, up, the health check, activate, an env restart or a hook.

12345678

1. migrate: failed — RECONCILIATION_REQUIRED — the uncertain step.
2. Output of migrate (last lines, secrets masked) — what the migration printed.
3. The outcome of “migrate” is uncertain, so this app is blocked. — the notice says who resolves it.
4. Inspect the host — reads the host; the app keeps serving.
5. Evidence — what runs on the host now, for example which release.
6. I checked the database: any migration this operation ran is either complete or handled. — your confirmation.
7. What you found (at least 8 characters, recorded in the audit) — your note.
8. Confirm and unblock — records it and unblocks the app.

Read the evidence and check your database, then confirm within 15 minutes with the inspectionId it printed:

With an assistant: “The last deploy of demo-crm failed. Show me the failed step and its output. If the operation says reconcile.by is "owner", inspect with the reconcile command and summarise what you find, then wait for me before recording anything.”

• Afterwards the failed operation stays failed. Deploy or roll back with a new key; migrations are not undone.
• Read the inspection before you choose. When it reports that the host still runs the last live release (on the page, “The host runs the last live release…”), confirming is enough: deploy the fix with a new key, and do not roll back, because a plain rollback would go one release further back.
• An administrator resolves it when routing, certificates, a restore or a quarantined host (a step that timed out or lost its connection) were involved: the page says “This needs an operator: …”. Trying yourself gives RECONCILE_NOT_ALLOWED. A migration that times out (15 minutes) also goes to an administrator; one that exits non-zero goes to you.

Roll back

A rollback recreates a kept release with a few seconds of downtime. It keeps the current domains, access, budget and last applied env, and runs no migration and no hooks. Without --release it goes to the newest healthy release other than the current one. Normally that is the previous release; after a rollback, it is the newer release you rolled back from. Check the release the preview names in to (its releaseTs in ps-apps releases), or name the release. Rollback is not on the web page or in MCP.

To roll back to a named release, list the releases, preview the rollback to the one you want, then apply it:

Only the boxes with --apply act. The two applies need different keys: they are different requests, so reusing one key answers IDEMPOTENCY_KEY_REUSED. The preview warns “Code rollback does not undo database migrations”.

After a failed health check

If the output shows a missing setting, as in the screenshot under Retry, set it with ps-apps env (§08) and deploy again with a new key. If the failed deploy was the app's first, ps-apps env answers CONFIG_REVIEW_REQUIRED: store the setting with REST (§08, Before the first deploy), then deploy. This failure is not uncertain: the cleanup state reads artifacts_retained.

Stop or delete an app

Stopping and deleting are done by REST, or by your assistant (“Stop demo-crm, then delete it. Keep its data volume.”). Load the token into one shell first.

The token travels to curl on its input (-H @-), never on its command line. Once the stop has succeeded, delete:

• Stop keeps volumes and releases. There is no start command: a deploy, or a rollback that names the current release, brings the app back.
• Delete removes the app's containers, routing and budget from its host and releases its addresses. The app must be stopped first (otherwise APP_RUNNING), unless it was never deployed. Data volumes are kept; on a shared host an administrator removes them.
• Without ?removeFromHost=1, a delete on your own host only forgets the app in PitchStation: its containers keep running and its addresses stay reserved for good. On a shared host the app is always removed.
• No operation may be running, and a stopped copy left by a move must be removed first (ps-apps moves --app 41 --remove-source MOVE_ID).

The deploy guide's Operate and Troubleshooting sections and the API reference's Operations cover the same ground.

§11Error codes and fixes

Turn any code into a next step. Each channel shows an error a little differently:

• Apps client: one JSON line on stderr, {"schemaVersion":1,"success":false,"error":"CODE: message …"}, and exit code 1. The message ends with what the server returned beyond its sentence: the fields or Compose settings to fix, the reason, the hosts placement refused, a missing scope and a correlation id. The same details follow as JSON keys.
• MCP: Error: CODE: message …, with the same details.
• Web page: the status message at the top, starting with the code.
• REST: the full JSON, including fields (names to fix, never values), detail, retryable and actor.

actor is publisher (you) or operator (the people who run the hosts). The API reference lists each code's HTTP status, whether it can be retried, and its actor: Errors.

Domains, DNS and certificates

Readiness and access

Plans, versions and keys

Operations and recovery

Upload and environment

Hosts, placement, budgets and quota

Moves, backups, terms and reports

Requests and lookups

Image archives, build ceiling and deploy settings

Codes outside the catalogue

Messages from the Apps client itself

§12Common problems

The problems people hit most, each as symptom, cause and fix.

The deploy fails its health check

Symptom. The deploy fails at health, and the app runs fine on your machine.

Cause. Read the first output line, unhealthy — last code: NNN. A code of zeros (000 or 000000) means nothing answered: the app listens on 127.0.0.1 instead of 0.0.0.0, crashed, or was still starting after about 60 seconds. A 3xx code is a redirect, 401 or 403 a login, and 404 a missing path. The log lines after it often show the crash.

Fix. Remember that the failing release is now serving (§10, After a failed health check). Retry if it was only slow. Otherwise bind 0.0.0.0, give healthPath a path that answers 200 to anyone (for example /api/health), and deploy with a new key. If you roll back, name the last good release.

exec format error, or a build fails on an ARM64 host

Symptom. The build or start fails with exec format error. Cause. An image or binary exists only for x86. Fix. Use multi-architecture images, or build arm64 ones. If ps-apps targets lists an x86 (amd64) host you may use, you can create the app there with "placement": {"arch": "amd64"}. With archives, IMAGE_ARCH_MISMATCH means: rebuild with the right --platform.

COMPOSE_POLICY_VIOLATION on a port

Cause. Only the web service may publish a port, and only on the host's loopback. Fix. Publish as "127.0.0.1:${HOST_PORT:-3000}:3000"; the right side is always your containerPort. Other services use expose. Inside the container the app still listens on 0.0.0.0.

DEPLOY_SETTINGS_INVALID on the migration

Cause. The migration command uses shell syntax, which is refused outside single quotes. Fix. Wrap it, for example sh -c 'npm run db:migrate && npm run seed', with ps-apps settings or Deploy settings (§08).

The upload is too large, or keeps failing in transit

Cause. The bundle is over 80 MiB compressed, 256 MiB unpacked or 20,000 files, or a big file was left in the project, such as an image archive or a dump. On a slow link, the deploy upload can also run out of its 15 minutes. Fix. ps-apps package shows what is packed. Move big files to the work folder, or list them in .pitchstationignore. Build elsewhere and deploy an image archive, or use a Devbox. If the client says the edge refused the upload, the request was too large for it.

Ownership proof not found

Fix. Add the TXT record exactly as shown, keep it, and press Verify DNS and ownership. An operation that waits in waiting_external tries again by itself within about 15 minutes. To try now, run ps-apps retry --app 41 --operation ID: the web page offers only Request cancellation for a waiting operation.

PLAN_EXPIRED after waiting for DNS

Cause. A plan lasts 15 minutes, and DNS often takes longer. Fix. Review the plan again (the TXT value stays the same), verify, and apply within 15 minutes.

QUOTA_EXCEEDED when creating an app

Fix. Delete an app you no longer need (stop it first, §10), ask an administrator for a higher quota, or use your own host (§14).

HOST_NOT_APPROVED or LIVE_DISABLED on apply

Fix. Only an administrator can approve the host or switch live publishing on. Dry runs still work meanwhile.

A webhook or OAuth callback gets 401 on a private app

Fix. Add its path prefix as a callback path (§06), and check every callback's signature in your app.

BUILD_LIMIT_EXCEEDED

Fix. Build elsewhere (an image archive or a Devbox), or make the build lighter. On hosts without the ceiling the 20-minute build limit applies, and a build killed at a time limit is uncertain and goes to an administrator.

A changed NEXT_PUBLIC value does not show

Cause. It is a build-time key, baked in when the image was built. Fix. Deploy again. Do not use ${…} inside build: on shared hosts (§08).

The app does not see a setting you stored

Cause and fix. Your own Compose file needs env_file: .env on the service that reads it (§08). A build-time key needs a redeploy. ps-apps env changes nothing until you add --apply, which restarts the app.

The first deploy lacks a setting, and ps-apps env answers CONFIG_REVIEW_REQUIRED

Fix. Until a release has gone live, store env with REST (§08, Before the first deploy), then deploy with a new key.

Everything answers RECONCILIATION_REQUIRED

Fix. Resolve the uncertain operation first (§10).

The connection dropped mid-deploy

Fix. Run the same command with the same key, or follow the operation with ps-apps operation … --watch. If the source changed in between, the same key answers IDEMPOTENCY_KEY_REUSED.

Every address answers 410

Fix. The expiry passed. Renew it or remove it (§06).

Everyone was signed out after an access change or a deploy

Cause. The plan or deploy carried a password, even an unchanged one. Fix. Leave password out of policy.json, and --password-file off redeploys, unless you mean to change it.

A public app never turns ready

Fix. If it is true, declare that the app has no separate restrictions (§06), then check readiness again.

PUBLIC_CONTENT_MISMATCH for an app that is not Vite

Fix. Deploy with --marker (or marker with MCP), or set Expected page identity in 1 · Domains.

Packaging fails

Fix. The error names the reason and the path. To look yourself: find DIR -type l lists links, grep -rl "PRIVATE KEY-----" DIR finds keys, and du shows sizes. List what should stay out in .pitchstationignore.

The app keeps restarting: out of memory

Fix. Last exit reads “(out of memory)”. Raise the budget (§09), or make the app use less memory.

Deploys wait in waiting_external, and changes say OPERATION_BUSY

Fix. Usually a TXT record was deleted. Fix DNS and retry, or cancel the operation. To drop the name instead, cancel first, then detach it (§05, Keep the TXT record).

The token or permission is refused

Fix. CAPABILITY_REQUIRED: ask an administrator. SCOPE_REQUIRED: make a token with the Apps preset. “Set PITCHSTATION_APPS_TOKEN”: run the client through the launcher. The MCP server needs PITCHSTATION_MCP_TOKEN (§02).

“--app must be a positive application ID”

Fix. --app takes the number from ps-apps list (41), not the slug.

No panels appear after choosing an app

Cause. The platform's publishing switch is off, or a legacy app needs an inventory. Fix. Read the status message and ask an administrator.

The first deploy fails at migrate: “unable to open database file”

Fix. The volume's mount point is owned by root. In the Dockerfile, create the data directory and chown it before USER (the deploy guide's contract shows it).

The second deploy fails at migrate

Fix. Seeding runs on every deploy. Make it safe to repeat: check before you create.

Data is gone after a release

Fix. Write data only to a named volume (§13).

Secrets are visible at some URL

Fix. Serve static files from an allowlist, not a catch-all, and rotate every exposed secret. The deploy guide's Troubleshooting table has more.

§13Data: volumes, backups, restore and moves

Keep data safe across releases, back it up, restore it, and move an app between hosts.

Where your data lives

Named volumes, kept on the host as ps-SLUG_NAME, survive every release; anything written inside the image does not. Deleting an app keeps its volumes; on a shared host an administrator removes them. Create and chown a volume's directory before USER in your Dockerfile, as the app contract shows.

Set up backups

Also set Keep on the host (1–10, default 5) and Also every day. A backup before each deploy is on by default; only "beforeDeploy": false in backup.json turns it off, as the page has no switch for it.

On the web page, choose How the data is backed up, then press Save backup settings: it saves at once, with no preview, and Not configured turns backups off.

12345678910

1. How the data is backed up — a command in one of your services, or a copy of named volumes.
2. Dump command (writes the backup to stdout) — for example pg_dump -U app -Fc app.
3. Restore command (reads it from stdin) — for example pg_restore -U app -d app --clean.
4. Keep on the host (1–10) — how many copies stay on the host.
5. Also every day — a daily backup as well.
6. Save backup settings — saves at once.
7. Back up now — starts a backup.
8. Where — host, platform, host + platform or gone.
9. Download — the platform's copy; the client has no download command.
10. Restore… — shows what will be replaced, then asks for the slug.

The preview shows the exact command the host will run. Unlike deploy hooks, the dump and restore commands run with sh -c inside the service, so pipes and && work. Each is one line of up to 1,000 characters, and a volumes backup names 1–8 volumes.

When backups run

• Before a deploy changes data: right before its first pre-deploy hook, else its migration, else its start. Only when backups are set up, beforeDeploy is not turned off, and the app already has a release. A failed backup stops that deploy before anything restarts (BACKUP_FAILED); the new build is already on the host, so deploy a fix before any env change.
• On demand: Back up now, or ps-apps backups --app 41 --apply --key …. Once its operation succeeds, reload the page to see the new backup in the list.
• Daily, if chosen: checked every hour; it runs when the last backup is older than 23.5 hours, and is skipped while the app is busy.

Where copies are kept

The app's host keeps the newest copies, as many as Keep on the host says. The platform keeps the newest 10 copies of up to 512 MB each; larger backups stay on the host only. Where shows host, platform, host + platform or gone, and Download gets the platform's copy.

Restore

On the web page, Restore… shows what will be replaced, then asks you to type the app's slug. The message reads “Restore accepted (operation …). Follow it under Operations.” A volumes restore stops the app, replaces the volumes and starts it again; a command restore feeds the dump to the restore command. The checksum is verified, a copy no longer on the host is sent back from the platform, and your code does not change.

Read what will be replaced. Then restore:

Customer instances: use fromApp and same-owner image archive references to reuse a definition and build. Customer tags appear in app list and spend; operator quotas require explicit administrator assignment. See repeating customer instances. Exact POST callbacks use POST /api/integrations/pitchstation/webhook in Private extras; the app verifies signatures. See private webhook endpoints.

Move to another host

On the web page, choose the Destination, tick This app keeps no data (move without a backup) if that is true, press Review move, then Move. It asks “Start the move? The app is down from the source stop until the destination serves.”

1234567

1. Destination — a host you may use.
2. This app keeps no data (move without a backup) — for apps with nothing to carry.
3. Review move — the plan; nothing changes yet.
4. Move — starts it, after a confirmation.
5. Address changes: … — the platform address before and after.
6. Steps: pull-release → stop-source → final-backup → … — the final volume backup follows the stop; the source stays stopped through cutover.
7. Point crm.example.com at 203.0.113.24 as soon as the source stops. — the DNS change for each custom domain. Make it when the source has stopped, not after the move: as the plan's last line says, the destination routes the app only once every name resolves to it.

Read the destination, the address change, the custom-domain records and the steps. Then start the move and follow it:

--region REGION (a region that ps-apps targets shows) instead of --target lets the platform pick a host there.

• What happens: the release is copied, the source stops, a final volume backup is taken, the release is copied to the destination, built there (or its image archive loaded), the data restored, then migrate, up, health and the routing switch.
• Downtime runs from the stop until the destination serves.
• The old copy: once the move succeeds, it stays stopped for 7 days, and its addresses redirect. Remove the stopped source now frees it sooner (ps-apps moves --app 41 --remove-source MOVE_ID).
• The platform address changes when the destination has a different base domain, including an isolated host in the same region (demo-crm.h7.apps-ap.pitchstation.ai).
• Custom domains: lower their DNS TTL (for example to 300 seconds) a day before. Point each one at the destination's address, which the preview lists, as soon as the move has stopped the source (stop-source in ps-apps moves). The destination routes the app and issues its certificates only once every name resolves to it; until then no address serves the app. After 45 minutes the move is recorded as failed after the switch, but its routing operation keeps waiting and finishes once DNS resolves. If that operation fails too, run a rollback that names the current release (§10).
• Requirements: a running release; a volume backup covering all app data, or the “keeps no data” box; data up to 512 MB; and a destination with the same CPU type, approved by an administrator, within your quota and slots. The destination must give the app another platform address (another base domain, such as an isolated host), unless per-app DNS is set up: two hosts under one base domain answer MOVE_UNSUPPORTED.
• A failure before the switch starts the app again where it was. Abort and restart the source works only for a move that was interrupted or is still queued (ps-apps moves --app 41 --abort MOVE_ID).
• After a platform restart, a move that already switched hosts is finalized if its routing operation succeeded; otherwise it is marked failed with the destination still current. Inspect the routing operation and retry routing there if needed. Failed moves keep the source without automatic removal; abort never restarts an already-switched source.
• While a move runs, changes answer MOVE_IN_PROGRESS.

The deploy guide covers Backups and restore and Moving to another host.

§14Your own host and spend

Reserve an isolated host inside your spend cap, and release it when you are done. An administrator launches each host you reserve.

• An isolated host runs your apps only, in Oregon or Singapore, arm64 or x86.
• From its first boot it runs the strict Compose rules and restricted outgoing traffic: no direct mail ports, no cloud metadata service, and a bounded rate of new connections.
• Budgets there are stored and only warn, unless the platform is set to enforce them.
• Its apps do not count against your shared-host quota.

Reserve one

On the web page, open Reserve an isolated host, fill Name, Size, Architecture and Region, then press Quote.

• The name is 1–32 lowercase letters, digits and hyphens, unique among your hosts.
• The architecture is required: arm64 or amd64.
• The quote shows a monthly figure for that size, checked against your spend cap. Reserve is enabled only when it fits.
• After Reserve the message reads “Reserved. An administrator launches it; it appears as live once approved.” A reservation nobody launches lapses after 24 hours.

The cap is one monthly limit covering your isolated hosts and dev instances, set by an administrator. COST_CAP means a reservation would go over it.

123456789

1. Monthly cap — your cap and what is committed against it.
2. Your isolated hosts — each host with its state, size, region and address.
3. Release — lets a host go; its apps must be moved or deleted first.
4. Reserve an isolated host — opens the form.
5. Name, Size, Architecture, Region — the host you want.
6. Quote — checks it against your cap.
7. Reserve — enabled when the quote fits.
8. The quote — whether it fits your cap.
9. What each app costs — each app's share of its host's running cost, and who pays (below).

Check the quote against your cap. Then reserve, and see your spend:

Its address

Apps on an isolated host get the slug, the host's own label and the region's base domain, for example demo-crm.h7.apps-ap.pitchstation.ai, unless per-app DNS is set up for the platform.

Host reports and growth

The host reports its memory and disk every 5 minutes. The list says “silent: no report for 15 minutes” when reports stop, and a “Growth” line proposes the next size when memory or disk stays above 85% for half an hour.

Release it

Cancel a reservation, or Release a live host. Releasing asks “Release …? An administrator terminates it; apps must be moved or deleted first.” A host that still has apps answers HOST_STATE_CONFLICT. In a terminal: ps-apps hosts --release ID, with the id that ps-apps hosts lists (not the host id from ps-apps targets). It acts at once, with no preview and no confirmation.

What each app costs shows each app's share of its host's running cost, split by memory budget. Paid by reads “You (your host)” for your own host, which counts in your spend cap, or “The platform (shared host)” for a shared host, which does not. The deploy guide covers this in Your own host and spend, and the host rules in Strict hosts, egress and acceptable use.

§15Limits and rules

Every number and rule in one place.

Limits

Rules

Compose rules. Shared and strict hosts refuse these settings; your own standard host warns about them:

• privileged;
• the host's or another container's network, PID, IPC, UTS, user or cgroup namespace;
• cap_add, devices and GPUs;
• cgroup_parent, security options that weaken isolation, and another runtime;
• the Docker socket; bind mounts, env files, build contexts and extends or include files outside the project;
• external volumes or networks, volume names outside your app's own, and drivers that are not local;
• any published port other than 127.0.0.1:${HOST_PORT} mapped to your container port, on the web service only;
• a ${…} in those settings other than ${PORT} and ${HOST_PORT}.

The deploy guide lists them with examples in Deploy a release.

• Strict hosts: only a reviewed list of Compose keys; container names start with ps-SLUG-; logs go to json-file or local; every service runs with no-new-privileges. See Strict hosts, egress and acceptable use.
• Exemptions: on an owner's own host only, an administrator can exempt one reviewed finding for one app. Shared hosts never exempt.
• Restricted egress (isolated hosts): no outgoing mail on ports 25, 465 or 587; no cloud metadata service; 30 new connections a second per container, with bursts to 120. Send mail through an email API over HTTPS.
• Publisher terms: when your platform requires them (§01). The version and text are on the Apps page.
• Reports and takedown: anyone can report an app at /abuse.html. An administrator can take an app down; it then answers 404, and you cannot change it until the takedown is lifted.
• Records: log reads (yours and administrators'), sign-ins with PitchStation, publishes and per-app events are recorded.

The overview's Limits and the API reference's Limits repeat the main numbers.

§16Glossary

§17FAQ

Does changing a domain or the access rebuild or restart my app?

No. Those plans show no builds and no restarts.

Can I see my app's password again?

No; only a hash is stored. Set a new one, which signs everyone out.

Will my app keep working if PitchStation itself is down?

Yes. Running apps keep serving, and passwords, access links, the expiry and redirects are enforced on the host, where certificates also renew. Changes, deploys, status and log reads, and new sign-ins with PitchStation need PitchStation.

Who can read my app's logs?

You and administrators. Every read is recorded, and values from your env are masked.

Can a teammate manage my app?

Each app belongs to the account that created it, and the page and API show only your own apps. Give teammates access to the running app with access links or Sign in with PitchStation.

Can I rename the slug or change the port later?

No (§08, What cannot change after creation).

How do I find a release id for a rollback?

Run ps-apps releases --app 41. It lists the 20 most recent releases and marks the live one.

Does a rollback bring back my old code?

Only when each release's built images carry their own tag, or the release came from an image archive with its own tags. Otherwise a rollback brings back the older Compose file but starts the newest build (§10, Roll back).

The client says “Unknown command” for archive, images, settings or releases

Download the client again with the install box in §02.

Why can't I accept the terms from the command line?

Accepting needs a signed-in browser session. Use the Apps page.

My MCP assistant finds no token

The server reads PITCHSTATION_MCP_TOKEN or PITCHSTATION_TOKEN, not PITCHSTATION_APPS_TOKEN. A token without the Apps scopes sees no Apps tools.

I don't see Apps in my sidebar

You need the permission from an administrator. You can still open /apps.html, which then shows CAPABILITY_REQUIRED. If an administrator has granted it and the item is still missing on another page, open pitchstation.ai/apps.html directly.

Is my data backed up off the host?

Only if you set up backups. The platform then keeps the newest 10 copies, up to 512 MB each, away from your app's host.

Can my app send email?

On isolated hosts, outgoing mail ports are blocked; use an email API over HTTPS.

Do search engines index my private app?

No. Private responses carry noindex, nofollow. They are not cached either, apart from cache paths and responses your app marks immutable, which only the signed-in viewer's browser keeps.

What happens to access links when I change the password?

Their sessions end, but the links still work until you revoke them or they expire. Opening a link again starts a new session of up to 12 hours.

What if I close my laptop during a deploy?

The operation continues. Follow it again with ps-apps operation … --watch, or repeat the same command with the same key.

How long can a deploy take at most?

Each step has its own limit: the upload 5 minutes, the build or image load 20, the pre-deploy backup 20, each deploy hook up to 30 (five before and five after), the migration 15, up 10 and health 5; any other remote step 30. Waiting for DNS adds up to about 90 minutes. So a deploy with hooks can take hours. --watch stops after 5 minutes, but the operation does not.

Do I need Docker on my computer?

Not to deploy: the client packs your project and the host builds it. You need Docker only to build image archives yourself, or to try the app locally.

Why was everyone signed out of my private app?

A plan or deploy carried a password, even an unchanged one; or the People and Teams list was cleared, which ends every account session. Leave password out of policy.json, and --password-file off later deploys, unless you mean to change it (§06).

§18For administrators

What only an administrator can do, and where it is done.

• Grant access: the admin page, Users, the person's feature access, “Deploy hosted apps (containers)”.
• Set a person's shared-host quota (0–100).
• Set the monthly spend cap, “Dev-instance cap (USD/month)”, which also covers isolated app hosts.
• Hosts: run the host check and onboarding, which installs the build ceiling and the host reporter; approve live publishing and pool membership; set strict rules and restricted egress; grant Compose exemptions on owner hosts.
• Launch the isolated hosts people reserve.
• Resolve operations marked reconcile.by: "operator".
• Handle abuse reports and takedowns, and decide whether publisher terms are required (a server setting).
• Switch live publishing on or off (LIVE_DISABLED).

The architecture page explains the moving parts: The pieces, milestone 2, milestones 3 and 4 and What stays stable. Host rules for owners are in the deploy guide's Your own host and Strict hosts.