Deploy a project

Deploy everything or only specific modules.

When you deploy your project to Keystroke, the platform builds a new runtime from that code, promotes it, and makes the project’s agents, workflows, and triggers available in the cloud.

Keystroke is deploy-first: edit src/, deploy, then run and inspect what’s deployed. Deploy often — a full deploy ships everything, or --filter redeploys a single module fast.

Where your project lives

Every Keystroke Cloud project gets a managed Git repository with two branches. main holds the deployed, live state. ks/draft is the shared work-in-progress draft — keystroke deploy publishes local edits through it, and platform agent sessions in the web app edit it directly. keystroke pull fetches and merges the shared draft by default (pass --published for the exact revision of the active deploy). Clients never push to managed main — deploy promotes the draft for you.

Deploying is keystroke deploy pointed at a specific project. For anything shared or production-facing, deploy often, and use keystroke pull to pick up teammates’ and platform-agent draft edits.

Before you deploy

You need:

• A Keystroke account and organization
• A project in that organization
• A codebase created with keystroke init
• Any cloud credentials your agents or workflows need

keystroke auth login
keystroke projects list

keystroke auth login is for local setups only. Hosted sessions — the in-app platform agent and MCP workspaces — already have credentials injected and must never run it.

If you do not have a project yet, create one:

keystroke projects create --name "Support automations"

Full deploy

Run a full deploy the first time you deploy to a project. Link the directory first (or pass --project for a one-off deploy):

keystroke projects link --project support-automations
keystroke deploy

keystroke deploy compares the pinned managed-Git commits locally, builds the accepted candidate, uploads it, and waits for a healthy platform activation. Snapshot-only projects also lint, typecheck, build, and upload. You do not need to run keystroke build, keystroke lint, or keystroke typecheck first.

A managed full deploy:

1. Pins main (M0) and draft (D0)
2. Composes the full draft delta onto an ephemeral candidate
3. Builds and uploads the candidate locally, then health-checks it on the platform
4. Fast-forwards main after health, then promotes the artifact

If the draft already matches main, deploy exits as a no-op.

After a successful deploy, runtime commands target your linked cloud project. Project targeting comes from project and organization in keystroke.config.ts (set by keystroke projects link). See project targeting.

Deploy from another directory

Use --dir when your current shell is not inside the project codebase:

keystroke deploy --dir ./apps/support-automations --project support-automations

When the directory is linked via keystroke projects link, you can omit --project.

The directory you deploy is the codebase that will define the platform project. Make sure it is the same tree you have been editing.

Verify a deploy

After deploy, check the deployment history and run something against the project:

keystroke projects deployments list --project support-automations
keystroke --project support-automations workflow run greeting --input '{"name":"Ada"}'

You can also inspect the project in the web app and review run history after agents or workflows run.

Pull the draft or the published revision

keystroke pull fetches the shared draft (ks/draft) and merges it into your local checkout, then installs dependencies. Use it to pick up teammates’ and platform-agent edits, bootstrap an empty directory, or resolve conflicts after a failed deploy merge.

keystroke pull --project support-automations            # shared draft, into the current directory
keystroke pull --project support-automations --dir ./support-automations
keystroke pull --project support-automations --published # active deploy revision instead

Pass --published to pull the active published artifact revision instead. That revision is the exact commit recorded on the active deploy — it may intentionally differ from current managed main while promotion or reconciliation is in flight.

An empty directory is initialized at the pulled commit. A non-empty non-Git directory is refused. If the merge conflicts, Git leaves conflict markers in place — resolve them, commit, and deploy again. Legacy snapshot-only artifacts still pull via the bulk source download.

Deploy only specific modules

After a project has an active full deploy, use --filter to redeploy one or more modules. Managed-Git deploys analyze dependency impact locally and prompt before expanded or unknown impact; pass --accept-impact in non-interactive environments.

keystroke deploy --filter agents/support
keystroke deploy --filter workflows/morning-check

Filters match build entry keys such as agents/support, workflows/morning-check, or triggers/incoming-message. They are exact matches, not globs.

See Deploy individual files for details.

Common mistakes

Mistake	What to do instead
Deploy merge conflicts	Run keystroke pull, resolve, commit, then deploy again
Dirty or uncommitted checkout	Commit your changes before keystroke deploy
Running --filter on the first deploy	Run a full deploy first
Deploying from the wrong directory	Pass --dir or change into the project codebase
Expecting .env to upload	Set credentials on the cloud project

Next steps

Manage projects

Create projects and invite teammates before you deploy.

Deploy individual files

Redeploy a targeted module or keep work-in-progress code out of production.

CLI reference

See the full deploy command reference.

Run history

Inspect what happens after your deployed agents and workflows run.