Get started with Lightsky

Your workspace API key authenticates the SDK + CLI. It looks like bk_…. Keys are shown once at creation; PyPI tokens are a different thing — don't mix them up.

Open /account → Scroll to "API keys" → create one → copy the value.

A "bot" is just a Python program with bot.py and requirements.txt. The worker installs the deps in a fresh venv and runs python bot.py. Pick whichever path fits how you build:

• Browser (no terminal needed). Zip the bot directory locally, drop it on /agents/new. Easiest for non-engineers and one-offs.
• CLI. pip install lightsei, then lightsei deploy ./my-bot. Best for iterating quickly while you build.
• GitHub push-to-deploy. Connect a repo on /github, register an agent path, then git push redeploys automatically. Best for production.

Save this as my-first-bot/bot.py:

import lightsei
import os
import time

# Lightsky reads your workspace API key from env (the worker injects
# it automatically when this bot is deployed via the dashboard or CLI).
lightsei.init(
    api_key=os.environ["LIGHTSEI_API_KEY"],
    agent_name="my-first-bot",
    version="0.1.0",
)


@lightsei.track
def do_some_work():
    # Anything you call inside a @lightsei.track function shows up as
    # a "run" on the dashboard. The OpenAI / Anthropic / Gemini SDKs
    # are auto-instrumented if installed — every LLM call gets
    # captured (model, tokens, cost) without code changes.
    print("hello from my bot")
    lightsei.emit("custom_event", {"note": "anything you want here"})


def main():
    while True:
        do_some_work()
        time.sleep(60)


if __name__ == "__main__":
    main()

And alongside it, my-first-bot/requirements.txt:

lightsei>=0.1.3

Add anthropic, openai, or google-generativeai to requirements.txt to make LLM calls — the SDK auto-instruments all three (no code changes needed).

Once your bot is deployed, you have several places to look:

• / — home / constellation map. Your bots show up as stars; Polaris (the orchestrator) is the bright center.
• /runs — every LLM call your bots have made, newest first. Tokens, latency, model, cost.
• /deployments — what the worker is actually running. Click a row to see live stdout/stderr from the bot.
• /dispatch — when bots dispatch commands to each other, they form chains. Each row is one chain; click to expand the timeline.

These aren't required for a working bot, but most people want them eventually:

• /notifications — wire up a Slack channel (incoming webhook URL) so Hermes can post agent results. Discord, Teams, Mattermost, generic webhook also supported.
• /github — register a repo so pushes to specific paths auto-redeploy agents. Polaris also reads MEMORY.md + TASKS.md from a registered repo if you set the corresponding workspace secrets.

Concepts that are useful to understand once you have one bot live:

• Agents. A logical name for a bot. Multiple deployments can share an agent name; only one runs at a time — the latest deploy retires the previous one automatically. Agents can also have a pinned LLM provider + model (set on the agent detail page) so swapping from Claude to Gemini is one DB write.
• Commands + dispatch chains. Bots can send commands to other bots (e.g. Polaris dispatches atlas.run_tests). Each dispatch fans out into a chain rooted at whoever triggered the first command (a webhook push, a scheduled tick, a UI click). The dispatch view renders chains as nested timelines.
• Approval gates. Agent-to-agent dispatches start in pending by default — a human clicks approve before the receiving bot runs. Auto-approval rules let you skip the click for trusted (source, target, kind) tuples.
• Validators. Per-event-kind schema or content checks. Set in the dashboard; failed validations either block the event (in strict mode) or just record an audit row (advisory).