Skip to content
Linkworld Docs

Quickstart

We’ll scaffold an app, run it locally, and deploy it to the platform. Pick your language — the rest of the docs covers both.

1. Install the CLI

Section titled “1. Install the CLI”
Terminal window
pip install linkworld
Terminal window
# verify
linkworld --version

2. Scaffold

Section titled “2. Scaffold”
Terminal window
linkworld init hello-world --lang python --github-owner you
cd hello-world

Or TypeScript:

Terminal window
linkworld init hello-world --lang typescript --github-owner you
cd hello-world

You’ll get a working app with:

  • linkworld.app.yaml — the manifest
  • main.py / app.ts — handlers (on_install + on_inbound)
  • requirements.txt — pinned to the latest published linkworld-sdk
  • Dockerfile — for image builds
  • AGENTS.md — primer your IDE LLM (Cursor / Claude Code / Codex) reads automatically; tells it which platform tools exist and how to discover the rest via the MCP server
  • linkworld.eval.yaml — passing eval suite out of the box. Run linkworld eval and you should see ✓ on every scenario before you write any code yourself.
  • .github/workflows/deploy.yml — CI that pushes to GHCR + registers with the platform
  • web/index.html + app.js + styles.css — frontend bundle that mounts at /apps/<slug> in the tenant shell, wired to the postMessage bridge. See Building app UIs.

3. Run locally

Section titled “3. Run locally”
Terminal window
# Python
pip install -r requirements.txt
LINKWORLD_LOCAL=1 python main.py
Terminal window
# TypeScript
npm install
npm run dev

Local mode boots a local HTTP server on port 8080 with MockTools and MockSecrets in place of the real platform. Trigger a tool:

Terminal window
curl -XPOST localhost:8080/tool/classify_text \
  -H 'Content-Type: application/json' \
  -d '{"text":"Q4 invoices"}'

Stub a platform tool the app calls back to:

Terminal window
curl -XPOST localhost:8080/__mock/tool \
  -d '{"name":"email_send","result":{"sent":true}}'

Trigger an inbound:

Terminal window
curl -XPOST localhost:8080/event/on_inbound \
  -d '{"message_id":"m1","channel":"email","from":"[email protected]","body":"hi",
       "subject":null,"received_at":"2026-04-26T10:00:00Z",
       "attachment_ids":[],"metadata":{}}'

4. Run the eval suite

Section titled “4. Run the eval suite”

Before deploying, verify the scaffold’s handlers behave as advertised:

Terminal window
linkworld eval

You should see all scenarios ✓ in green. The scaffold’s linkworld.eval.yaml exercises the install handler and one representative path per template (sweep + bot-noise filter for email-triage, etc.). Add a scenario whenever you add a new code path — it’s faster than re-deploying to test classification logic.

5. Sign in

Section titled “5. Sign in”
Terminal window
linkworld login

Opens a browser → GitHub OAuth. Falls back to linkworld login --token <jwt> if you’ve been issued an admin token.

6. Document for end users

Section titled “6. Document for end users”

linkworld init scaffolded app_docs/user.md next to your manifest. Open it and replace the placeholders with a 30-second elevator pitch + the 2-3 things a non-developer end-user actually needs to know about your app.

Terminal window
$EDITOR app_docs/user.md

When you deploy, linkworld deploy auto-uploads everything under app_docs/**/*.md; docs.linkworld.ai/apps/<your-slug>/ renders the narrative + an auto-generated Reference section (your tools, scopes, agents, install settings) on the next docs build. The same content also appears in the in-app Help tab.

Apps without a user.md don’t show up on the docs site at all — the marketplace listing covers app discovery, the docs site is reserved for apps with real end-user content. See Documenting your app for the full spec, caps, and the canonical Pipeline example.

7. Deploy

Section titled “7. Deploy”
Terminal window
git init && git add . && git commit -m "init"
git remote add origin [email protected]:you/hello-world.git
git push -u origin main
git tag v0.1.0 && git push --tags

The included GitHub Actions workflow builds the image, pushes to GHCR, and runs linkworld deploy --skip-build --version 0.1.0 against the platform. You’ll see the new version in the dev console.

What’s next

Section titled “What’s next”