First-Time Setup

Project scaffolding

When Runsight starts for the first time, the API server creates the project structure automatically:

Directories and marker file. Runsight creates custom/workflows/ and custom/souls/, plus a .runsight-project marker file and 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-project        # Project marker file
├── .runsight/               # Gitignored runtime data
│   ├── settings.yaml        # App settings
│   └── secrets.env          # API keys (gitignored)
└── custom/
    ├── providers/            # Provider YAML files
    ├── souls/                # Soul definitions
    └── workflows/            # Workflow definitions

Next steps

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