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 (one tool, one inbound)
  • Dockerfile — for image builds
  • .github/workflows/deploy.yml — CI that pushes to GHCR + registers with the platform

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. Sign in

Section titled “4. 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.

5. Deploy

Section titled “5. 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”