# Kedge documentation > A lightweight, globally distributed cloud platform. Deploy static sites, HTML apps with live data, shebang handlers, container services, and databases from a source tree, a Git push, a prebuilt image, or a task for a coding agent in a persistent workspace. Every app includes a replicated SQLite database and file tree, scales to zero, and runs in hardware-isolated VMs. --- # quickstart Source: https://kedge.dev/docs/quickstart Publish a static page: ```bash ssh kedge.dev publish '# Hello, world!' ``` Your SSH key identifies your account. Markdown becomes HTML. ## a function Add a `#!` shebang to publish a script that runs on each request: ```bash printf '#!/bin/bash \n uptime' | ssh kedge.dev ``` ## the `kedge` shortcut Install the optional `kedge` shortcut, a small wrapper around `ssh kedge.dev`: ```bash ssh kedge.dev setup | sh ``` It also adds `kedge up`, a Git commit-and-push helper for source directories. ## start with a task Coding-agent sessions need a claimed account. Claim the SSH key once, then describe the task: ```bash kedge login kedge agent "build a small status page" ``` Kedge creates **My workspace** on first use, gives the task its own project, and starts an interactive session. A small project usually ends with a working demo URL; the private session URL lets you continue in a browser. See [coding agents & workspaces](/docs/agents) for follow-ups, named workspaces, and other clients. ## a routed site Deploy a directory, and the files become a route tree: ```bash mkdir -p about cat > index.html <<'EOF'

Field notes

A tiny site with more than one route.

How this site works → EOF cat > about/index.html <<'EOF'

About this site

The directory tree becomes the URL tree.

← Back home EOF kedge up ``` `index.html` serves `/`; `about/index.html` serves `/about/`. `kedge up` derives a default app name from the working directory. Switch branches for an isolated preview: ```bash if git fetch -q origin refs/heads/tweak >/dev/null 2>&1; then git reset -q --hard git checkout -q -B tweak FETCH_HEAD else git checkout -q -b tweak fi mkdir -p about if [ ! -f index.html ]; then cat > index.html <<'EOF'

Field notes

How this site works → EOF fi cat > about/index.html <<'EOF'

Previewing a new route

This only exists on the tweak branch.

← Back home EOF kedge up ``` The preview gets its own URL; `main` stays live. ## an HTML app Add `data-kedge` to ordinary HTML for shared, live data without writing an application server, SQL, or JavaScript. ```bash cat > index.html <<'EOF' Clicks

Clicks

{{clicks | plural:click}} EOF kedge up ``` At deploy time, Kedge parses the bindings, creates the counter column, and manages the underlying database. Increments merge without losing simultaneous clicks, and bound values update live. See [HTML apps](/docs/html-apps) for a more detailed example. ## a database and a filesystem Every app has `/shared.db` and `/shared/`, ordinary local paths for state that needs code. Two handlers, the same rollup: ```bash cat > index.sh <<'EOF' #!/usr/bin/env bash agent=${HTTP_USER_AGENT//"'"/"''"} printf 'Content-Type: text/plain\n\n' sqlite3 -header /shared.db " CREATE TABLE IF NOT EXISTS hits( id INTEGER PRIMARY KEY, dc TEXT, agent TEXT, at TEXT DEFAULT (datetime('now'))); INSERT INTO hits(dc, agent) VALUES('$KEDGE_DC', '$agent'); SELECT dc, count(*) AS hits, max(at) AS latest, agent FROM hits GROUP BY dc, agent ORDER BY hits DESC;" EOF cat > files.sh <<'EOF' #!/usr/bin/env bash echo "$KEDGE_DC $HTTP_USER_AGENT" >> /shared/agents.log printf 'Content-Type: text/plain\n\n' sort /shared/agents.log | uniq -c | sort -rn EOF kedge up ``` `/` groups the request log in SQL; `/files` appends a line and counts it with `sort | uniq -c`. Both replicate across instances and regions. Use the database when you want a query or an index. See [shared data](/docs/shared-data). ## an app built from source Kedge detects common frameworks and builds them from source. This Rust service reports its optimized binary and resident-memory sizes: ```bash mkdir -p src cat > src/main.rs <<'EOF' use memory_stats::memory_stats; use std::env::{current_exe, var}; use tiny_http::{Response, Server}; fn main() { let port = var("PORT").unwrap_or_else(|_| "8080".into()); let srv = Server::http(format!("0.0.0.0:{port}")).unwrap(); let bin = current_exe().unwrap().metadata().unwrap().len() / 1024; for (n, req) in srv.incoming_requests().enumerate() { let rss = memory_stats().unwrap().physical_mem / 1024; let body = format!("release binary: {bin} KiB\n\ process RSS: {rss} KiB\nrequest: {}\n", n + 1); req.respond(Response::from_string(body)).unwrap(); } } EOF cat > Cargo.toml <<'EOF' [package] name = "quickstart-rust" version = "0.1.0" edition = "2021" [dependencies] memory-stats = "1.2" tiny_http = "0.12" [profile.release] strip = true EOF kedge up ``` `Cargo.toml` is the build plan; Kedge compiles a release binary and supplies `$PORT`. ## a prebuilt image Publish an existing Docker image straight from a public registry: ```bash kedge publish --app "$(kedge whoami)-quickstart-httpbin" \ --image ghcr.io/mccutchen/go-httpbin:2.23.1 ``` ## a Dockerfile Use a Dockerfile when the image itself is the point. This multi-stage Go build compiles a static binary and copies it into an empty `scratch` image: ```bash cat > main.go <<'EOF' package main import "net/http" func main() { http.HandleFunc("/", func(w http.ResponseWriter, _ *http.Request) { w.Write([]byte("Hello from scratch.\n")) }) http.ListenAndServe(":8080", nil) } EOF cat > Dockerfile <<'EOF' FROM golang:1.24-alpine AS build COPY main.go / RUN CGO_ENABLED=0 go build -o /server /main.go FROM scratch COPY --from=build /server / EXPOSE 8080 ENTRYPOINT ["/server"] EOF kedge up ``` See [builds & images](/docs/builds) for the full build order. ## clean up Delete the example apps: ```bash kedge delete 'hello-world-*' 'bash-*' \ "$(kedge whoami)-quickstart*" ``` ## beyond the defaults Software that expects local disk, such as Postgres, a game server, or a dev box, needs a [persistent volume](/docs/volumes): ```bash kedge up --volume /data ``` Connecting a repository through [GitHub deploys](/docs/github) gives every pull request its own preview. --- # coding agents & workspaces Source: https://kedge.dev/docs/agents Agent sessions need a claimed account. Claim the SSH key once, then start with one task: ```bash 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: ```bash 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](/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: ```bash 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](/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: ```bash 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: ```bash kedge workspace run design-lab "add keyboard navigation" kedge workspace ps design-lab kedge workspace stop design-lab kedge workspace archive design-lab ``` 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](/.well-known/agent-skills/kedge/SKILL.md) 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](/docs/billing#coding-agent-model-usage). 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. --- # app model Source: https://kedge.dev/docs/app-model An **app** is the unit you name, deploy, and manage. Every app has a source tree, a database, and a deploy history, whatever it is built from. Every app runs as one of three things, marked by a glyph in `kedge apps` and the web console: | mark | type | you give it | it runs | |---|---|---|---| | `▤` | [site](/docs/sites) | files, some of which can execute | at the edge, [handlers](/docs/handlers) per request in a VM | | `⬡` | [service](/docs/builds) | source, a Dockerfile, or an image | as a pooled process, scaled to demand and to zero | | `▣` | [machine](/docs/volumes) | either, plus a persistent volume | as one VM per ordinal, kept for life | A label beside the mark names the variation, such as `site · files + handlers`, and a second mark records how the content arrived. Most apps are sites, and a site needs no server code of its own. A service is the escape hatch when a workload wants a long-lived process; a [Compose](/docs/compose) file defines several services as one app. ## instances and machines A service runs in a hardware-isolated VM. How those VMs are held is one choice: | | [instances](/docs/runtime) | [machines](/docs/volumes) | |---|---|---| | identity | disposable | an ordinal, kept for life | | storage | none of its own | a persistent volume | | scaling | follows demand, down to zero | a fixed count, minimum one | | address | one virtual address | one each, plus one for the set | Instances are the default: Kedge starts them near demand and removes them when idle. Declaring a [persistent volume](/docs/volumes) moves the app onto machines instead, each keeping its identity and disk across deploys and host moves. A machine always belongs to an app and is addressed by its ordinal within it. There is no separate machine resource to create or destroy. A [workspace](/docs/agents) is a machine you develop on rather than serve from, carrying your checkout, tools, and build caches on the same durable disk. It needs no service at all. Every app includes [`/shared.db`](/docs/shared-data) and [`/shared/`](/docs/shared-data#shared-files) for state shared across instances and regions. Reach for a persistent volume only when software requires a private local filesystem. Apps are global resources. Public routes receive HTTPS, private services resolve through account-local DNS, and an [authentication policy](/docs/authentication) can gate any app type at ingress. --- # deploy workflows Source: https://kedge.dev/docs/deploy Every source deploy is an ordinary Git history. `kedge up`, a manual push, GitHub, the browser editor, and an import all feed the same build and cutover pipeline. The files select a site, automatic source build, Dockerfile build, or Compose deploy; each path creates or updates an app. See [builds & images](/docs/builds). ## from a directory From a project directory, the shortcut can initialize Git when needed, commit the working tree, add a username-scoped `kedge` remote, and push the current branch: ```bash kedge up --dry-run kedge up ``` The first push creates the app. The production branch defaults to `main` and can be changed with top-level `x-kedge.production-branch`. Any other branch of a single-service app is an isolated preview at `https://--.kedge.run`. Its managed database and files branch from production once; redeploys retain preview changes. Multi-service previews are not available. Previews expire automatically. See [shared data](/docs/shared-data#previews-and-forks) for storage boundaries. Identical Git trees reuse the prior build, so a retry or amended commit with unchanged content redeploys in milliseconds. Apps deployed by push keep their source durably: the app page shows a `git clone` snippet, and the **edit code** button opens a browser editor over the repo; saving a file commits and redeploys through the same pipeline as a push. ## other ways in - `kedge import [name]` clones a public repository into an app you own and can continue pushing. - `kedge publish --app --image ` deploys a public prebuilt image. - Inline content, piped stdin, and `scp` publish documents, functions, and file trees without creating a local repository first. - The web editor commits each save into the same durable repository. ## app names `kedge up` derives the app name from the directory and prefixes your username. The manual equivalent is a namespaced Kedge remote and a push: ```bash git remote add kedge ssh://kedge.dev/$(kedge whoami)/myapp.git git push kedge main ``` The namespaced path creates `-myapp`, and no other account can create any `-*` name. A bare repo name (`ssh://kedge.dev/myapp.git`) instead claims `myapp` first-come from the shared global pool. ## zero-downtime cutover The current version keeps serving through the build. The new version boots, is snapshotted, and must serve a request before traffic moves. If it cannot, the deploy fails and the current version stays live. `kedge rollback ` sends the previous version through the same gate. Services with [persistent volumes](/docs/volumes) roll machines in place because each volume has one writer. [Runtime & scaling](/docs/runtime#readiness-and-health) explains the snapshot and health checks behind this gate. ## GitHub deploys The Kedge GitHub App connects selected repositories without a long-lived personal access token. It deploys the production branch, creates pull-request previews, and reports status to GitHub. See [GitHub deploys](/docs/github). ## update a Compose app Redeploying `compose.yaml` reconciles its Kedge app. New services are added, shared builds are reused, and generated secrets keep their values. Kedge refuses edits that would implicitly discard persistent state. The exact model and supported fields live in the [Compose reference](/docs/compose). ## environment and secrets Commit non-secret defaults under a service's `environment`. Store deploy-time values with `kedge env ` or the app page. Standard Compose interpolation can make a value mandatory: ```yaml services: web: environment: API_KEY: ${API_KEY:?set with kedge env} ``` Compose `secrets` and `configs` deliver values as guest files. The `x-kedge` generator can mint a secret once without putting the value in Git; see [Compose secrets](/docs/compose#secrets-and-configs). ## time-limited apps An app expiration deletes its route, compute, snapshot, and app record at the deadline. Set it on the app page or with `kedge expire <48h|7d|timestamp|clear>`. Previews use the same cleanup. --- # sites & routing Source: https://kedge.dev/docs/sites A site is a source tree with no server build. Ordinary files are published to the edge CDN; files whose first line is a `#!` shebang become [handlers](/docs/handlers) at the same hostname. This page covers file routing and static delivery; the handlers guide covers executable routes. HTML or Markdown files with data bindings become [server-rendered HTML applications](/docs/html-apps) on the same site. ## routes from paths ```text index.html -> / about.html -> /about guide.md -> /guide logo.png -> /logo.png api/visit.sh -> /api/visit (handler) blog/[...].py -> /blog/* (handler catch-all) ``` `.html`, `.md`, and handler extensions are stripped. `index` is the directory index, so `about/index.html` serves `/about/`. A bracket catch-all owns its subtree and receives the remaining path as `PATH_INFO`. Two files claiming one route fail the deploy. The deploy output prints the resolved route table. ## Markdown and public files Markdown renders to HTML at publish time. `index.md`, `_index.md`, or `README.md` can be a directory index, making a documentation tree a static site with no build step. A `public/` directory is copied to the site root verbatim. Its files are served as-is rather than Markdown-rendered. ## fallback routes For a site with no services, a Kedge Compose extension can set an SPA fallback: ```yaml x-kedge: static: fallback: /index.html ``` An unmatched path then serves that static file. Without a fallback, the edge answers 404 without waking compute. If repository scripts contain shebangs but are not web handlers, exclude their directories explicitly: ```yaml x-kedge: static: handler-excludes: [scripts, tools] ``` ## publishing a tree `kedge up` deploys a local directory through Git. For a one-off upload, `scp` the tree to the SSH endpoint; a trailing remote directory names the app. A single piped page is the smallest case in the [quickstart](/docs/quickstart). See [deploy workflows](/docs/deploy) for Git history, previews, and other source paths. Static responses carry validators and edge-cache headers. Deploying updates the route manifest and purges stale objects automatically; there is no cache configuration step. [Network & domains](/docs/network#public-ingress-and-cdn) describes the global serving path. --- # HTML apps Source: https://kedge.dev/docs/html-apps An HTML app is a web page with `data-kedge` bindings. Kedge compiles its reads, writes, and schema at deploy time and renders requests against the app's local database replica. HTML apps also integrate with [app authentication](/docs/authentication), account controls, and ownership-aware writes. ## a guestbook ```bash cat > index.html <<'EOF' Guestbook
  • No messages yet.
EOF kedge up ``` The form creates `messages` records. The list renders its `