Skip to content

getting-started.md

Latest commit

 

History

History
119 lines (84 loc) · 2.97 KB

getting-started.md

File metadata and controls

119 lines (84 loc) · 2.97 KB
Raw

Getting Started

This guide takes you from a fresh install to your first physical-AI agent in a few minutes.

Prerequisite: a Syscity binary. Either install a release or build from source. Check it works:

syscity --version

1. Run the setup wizard

syscity setup

The interactive wizard walks you through choosing an LLM provider, entering an API key, and picking a default model. It writes everything to ~/.syscity/syscity.toml.

Prefer to configure by hand? Skip the wizard and set values directly:

syscity config set providers.openai.api_key=sk-xxxxx
syscity config set model=gpt-4o

Or via environment variables (handy for CI / containers):

export SYSCITY_API_KEY="your-api-key"
export SYSCITY_MODEL="gpt-4o"

Validate the configuration at any time:

syscity config            # show current config
syscity doctor run        # run diagnostic checks

2. Start the daemon

# Background daemon: web UI + HTTP API + WebSocket on port 18080
syscity start

# Or stay in the foreground (logs to your terminal)
syscity start --foreground

Check it came up:

syscity status
syscity logs -f          # tail the logs

The Web UI is now at http://127.0.0.1:18080.

3. Talk to your agent

Two interactive options:

Web UI — open http://127.0.0.1:18080 in a browser.

Terminal client — attach the TUI to the running daemon:

syscity tui

Try a physical-AI prompt:

Take a screenshot and tell me what's on my screen.

On macOS the agent can also read the accessibility tree, click and type, run AppleScript, and execute shell commands. Grant Screen Recording and Accessibility permissions in System Settings → Privacy & Security for the full experience.

4. Connect a messaging channel (optional)

Syscity can run as a bot on Telegram, Discord, Slack, and more:

# Example: add a Telegram bot
syscity channel add telegram --token <BOT_TOKEN>

# List configured channels
syscity channel list

See channels for per-platform setup.

5. Useful day-to-day commands

Command Purpose
syscity status Is the daemon running?
syscity logs -f Tail daemon logs
syscity reload Reload config + plugins without restarting
syscity stop Stop the daemon
syscity session Inspect / manage sessions
syscity memory Search and manage vector memory
syscity skill Manage skills
syscity provider List / switch LLM providers
syscity capabilities Show available OS capability sets
syscity export Export conversations / memories

Run syscity --help or syscity <command> --help for the full list.

Where to go next