Agent sessions need a claimed account. Claim the SSH key once, then start with one task:

kedge login
kedge agent "build a small status page"

Kedge starts its built-in app agent directly. For a small new site or app, the agent usually publishes the first working demo and returns its URL. The terminal stays at a > prompt for follow-up turns.

Continue an existing app with its current source and revision:

kedge agent --app myapp "add a leaderboard"
kedge agent --app myapp

The first form runs that turn before opening the prompt. The second opens the prompt immediately for discussion, review, or changes. Publishing commits the updated source and deploys the same app. If its revision changes concurrently, the agent refreshes independent changes and resolves overlapping files before retrying. It can also run the ordinary app-scoped Kedge commands and send cookie-preserving GET and POST requests to the live app. Apps linked to GitHub remain push-only.

You can also start a task from /agents.

make, build, and create are aliases that read as the prompt's first word, so kedge make me a status page needs no quoting. With raw SSH, use the same explicit form: ssh kedge.dev agent 'make me a status page'. ssh kedge.dev agent --app myapp opens the existing-app prompt without requiring -t. One-shots print the app URL on stdout, with sparse progress and any failures on stderr. A new app must publish before the turn succeeds; an existing-app turn can complete a database or other live operation without redeploying unchanged source. Existing-app one-shots and interactive turns also show the final reply on stderr; stdout remains only the app URL. Put --verbose after the agent verb to stream tool activity. Use an explicit publish command when those words are literal page content.

To use a connected subscription directly from the terminal, choose its CLI:

kedge agent --claude "review this project"
kedge agent --codex "fix the failing tests"

The first run signs in through the same terminal, then continues into the agent. That sign-in also makes the provider available to sessions opened from the workspace UI.

continue a session

Type follow-up messages at the > prompt. The built-in agent keeps its conversation and unpublished edits for that SSH connection; Ctrl-D ends it. Published source remains with the app, and a later --app session loads the latest revision. Pass --verbose to include its tool trace.

Subscription-agent sessions run in My workspace. Ctrl-D detaches without stopping them. Their private browser URL is printed when they start, and /agents lists sessions across all workspaces without waking them.

projects and workspaces

Each top-level task in My workspace gets a separate Git project directory. Sessions, installed tools, and the complete writable filesystem survive restarts and host moves.

Projects in one workspace still share a VM and filesystem. Use a named workspace when you need separate tools, files, or a stronger boundary between projects.

use a named workspace

Create a workspace, optionally connected to an existing app:

kedge workspace create design-lab
kedge workspace create api-work api-app

Run from a terminal, create leaves you in a shell inside the new workspace. Scripted, it prints the name and returns.

Dispatch and manage tasks without opening the workspace first:

kedge workspace run design-lab "add keyboard navigation"
kedge workspace ps design-lab
kedge workspace stop design-lab <execution>
kedge workspace archive design-lab <execution>

Connecting an app checks out its code and makes deploys from that workspace target it by default. You can change the connection from the workspace page.

other ways to connect

The private workspace URL opens the full session UI in a browser. To connect from a phone or desktop, open the workspace page and choose pair a device. Enable the end-to-end encrypted relay, then scan the QR code or paste the pairing link into the app. Kedge runs the relay, but it can see only connection metadata—not session content—and stays off until you pair. Treat the QR code and link as credentials. Start a workspace again before reconnecting if you explicitly stopped it.

On a workspace page, connect a provider shows whether Claude and Codex are connected. Sign in there once to make that provider available when starting an agent session. After signing in, start remote control makes that workspace available in the provider's native remote app; return to the same page to turn it off. Hosted Codex sessions use Luna in fast mode and omit Codex plugin and app catalogs to keep remote startup bounded.

If an agent is already running on your computer, install the Kedge skill to teach it how to deploy and operate Kedge apps. That is separate from the hosted sessions above.

usage and deletion

Platform model use has its own monthly allowance and appears in the billing ledger. Workspace compute and storage use the ordinary resource rates.

Workspaces sleep after ten quiet minutes by default and wake on the next request. Their page distinguishes starting, awake, sleeping, paused, stopped, and failed workspaces, and the app logs record each sleep and wake with a timestamp. Pairing a device or running a provider remote control keeps the workspace awake; turn those off when you want to test or use idle suspend. Storage remains durable and billable while compute sleeps.

Deleting a workspace stops it and leaves its volume orphaned until you remove that explicitly with kedge volumes rm. Push or copy out anything important first; retained volumes are not a source-control substitute.