First-Time Setup

Project scaffolding

When Runsight starts for the first time, the API server creates a blank workspace automatically:

Empty workspace directories. Runsight creates empty custom/workflows/, custom/souls/, and custom/tools/ directories, plus a .gitignore that excludes .runsight/ and .canvas/.
Git initialization. If no .git directory exists, Runsight runs git init, sets a local git user (runsight@localhost), stages the scaffolded files, and creates an initial commit.
Settings file. .runsight/settings.yaml is created with onboarding_completed: false. See Settings for the full reference.

API key setup

Runsight needs an API key for at least one LLM provider before you can run workflows.

Environment variables are checked first. If you already have a key exported in your shell, Runsight picks it up automatically — no further configuration needed:

export OPENAI_API_KEY=sk-...

If no environment variable is found, Runsight checks .runsight/secrets.env. This file is created when you add a provider through the Settings page. The resolution order is:

os.environ (real environment variable)
.runsight/secrets.env (managed by Runsight, gitignored)

Provider YAML files in custom/providers/ store references like ${OPENAI_API_KEY}, never raw keys.

Provider configuration

Once your API key is available, configure a provider through Settings > Providers > Add Provider in the sidebar. Runsight auto-tests the connection and populates the model list on success.

See Providers for supported providers, storage format, and how souls reference them.

Project directory after setup

your-project/
├── .git/                    # Auto-initialized git repo
├── .gitignore               # Excludes .runsight/ and .canvas/
├── .runsight/               # Gitignored runtime data
│   ├── settings.yaml        # App settings
│   └── secrets.env          # API keys (gitignored)
└── custom/
    ├── providers/            # Provider YAML files
    ├── souls/                # Empty until you add your own souls
    ├── tools/                # Empty until you add your own tools
    └── workflows/            # Empty until you create your first workflow

Next steps

Runsight does not ship sample workflow, soul, or tool YAML into your runtime workspace. After first launch, create your first workflow through onboarding or by adding files under custom/.

Providers — add and manage LLM providers
Quickstart — create and run your first workflow
Settings — full settings.yaml reference