Credentials, Scripts & Backups

Stib provides three key administration features for managing your instance: credentials for AI agent authentication, project scripts for running custom commands, and backups & exports for data protection.

INFO

Credential management and backups require super admin privileges (or are available when authentication is disabled). Project scripts are configured per project by any user with project access.

Credentials

Stib agents need credentials to interact with Claude. Two credential types are supported, each with a different authentication method.

Credential Types

Feature	API Key	OAuth Profile
Authentication	Static secret key	Browser-based OAuth flow
Format	`sk-ant-*` string	OAuth token in profile directory
Storage	AES-256-GCM encrypted in database	Profile directory (`~/.stib-claude-profiles/cred-{uuid}`)
Usage Tracking	Not available	5-hour and 7-day usage quotas
Best For	API access, automation	Interactive use with Anthropic account

Adding an API Key

WARNING

The STIB_ENCRYPTION_KEY environment variable must be configured before adding API keys. Without it, Stib cannot encrypt key values and the operation will fail. See Configuration for setup instructions.

Go to Settings → Credentials
Click Add Credential and select API Key
Enter a label (e.g., "Production Key", "Team Key")
Paste your Claude API key (starts with sk-ant-)
Stib validates the key format and tests it against the Anthropic API
Once validated, the key is encrypted and stored securely

WARNING

API keys are encrypted at rest using AES-256-GCM. The key value is never exposed in API responses — only the label and status are returned.

Adding an OAuth Profile

Go to Settings → Credentials
Click Add Credential and select OAuth Profile
Enter a label for this profile
Click Start Login — your browser opens the Anthropic OAuth page
Sign in with your Anthropic account and authorize Stib
Stib polls for completion and stores the OAuth tokens in a dedicated profile directory
Once complete, the profile is ready to use

INFO

OAuth profiles store tokens in ~/.stib-claude-profiles/cred-{uuid}/. On macOS, sensitive tokens are stored in the system Keychain for added security.

Credential Assignment

Stib uses a cascade resolution to determine which credential an agent uses. The most specific assignment wins:

┌─────────────────────────────────────────────┐
│  1. Card-level credential      (highest)    │
│     Set on individual card settings         │
├─────────────────────────────────────────────┤
│  2. Project-level credential                │
│     Set in Project Settings → General       │
├─────────────────────────────────────────────┤
│  3. Organization default credential         │
│     Set in Organization Settings            │
├─────────────────────────────────────────────┤
│  4. System default             (lowest)     │
│     Falls back to ~/.claude/ directory      │
└─────────────────────────────────────────────┘

This allows you to set a default credential for your organization while overriding it for specific projects or individual cards.

Usage Monitoring

OAuth profiles provide real-time usage data from Anthropic:

Quota	Description
5-hour window	Usage percentage over a rolling 5-hour period
7-day window	Usage percentage over a rolling 7-day period

Usage bars are displayed next to each OAuth credential with color-coded thresholds:

Color	Utilization	Meaning
🟢 Green	0–70%	Normal usage
🟡 Yellow	71–90%	Moderate usage
🟠 Orange	91–94%	High usage, approaching limit
🔴 Red	95–100%	At or near rate limit

TIP

Usage data refreshes automatically every 5 minutes via the background credential checker. When a quota resets, the timer and utilization percentage update on the next check cycle.

Verification & Health

Stib runs a background credential checker every 5 minutes that:

Validates API keys against the Anthropic API
Refreshes OAuth tokens and fetches the latest usage data
Updates credential metadata (email, subscription type, verification status)

Each credential shows a status indicator:

Status	Meaning
✅ Verified	Credential is valid and working
⚠️ Unverified	Not yet checked or check pending
❌ Invalid	Key rejected or OAuth tokens expired

You can also trigger a manual verification by clicking the verify button on any credential.

Managing Credentials

From the credentials list in Settings, you can:

Edit label — Rename a credential for clarity
Delete — Remove a credential (references in organizations, projects, and cards are automatically cleared)
Set as default — Assign a credential as the organization default
Refresh OAuth — Re-trigger token refresh for OAuth profiles
Verify — Manually check credential validity

Encryption & Security

Stib encrypts all API keys at rest using AES-256-GCM symmetric encryption.

Setting	Description
`STIB_ENCRYPTION_KEY`	Hex-encoded 32-byte key used for encrypting API key values and backup provider secrets

Generate an encryption key:

bash

openssl rand -hex 32

Set it as an environment variable before starting Stib:

bash

export STIB_ENCRYPTION_KEY="your-64-character-hex-string"

WARNING

If you lose the STIB_ENCRYPTION_KEY, encrypted API keys cannot be decrypted. Store it securely alongside your Stib configuration.

Security guarantees:

API key values are never returned in API responses
Deletion cascades: removing a credential automatically nullifies references in organizations, projects, and cards
OAuth tokens are stored in isolated profile directories, with macOS Keychain integration where available

Project Scripts

Project scripts let you define and run custom shell commands directly from the Stib interface — useful for builds, tests, deployments, or any recurring task.

Configuring Scripts

Go to Project Settings → Scripts
Click Add Script
Fill in the script details:

Field	Required	Description
Name	Yes	Display name (e.g., "Build", "Test", "Deploy")
Command	Yes	Shell command to execute (e.g., `npm run test`)
Description	No	Optional description shown in the dropdown

Drag and drop scripts to reorder them — the order is reflected in the run menu

Running Scripts

Click the play button (▶) in the project top bar
If multiple scripts are configured, a dropdown menu appears — select the script to run
An output dialog opens showing real-time execution output:
- Standard output is displayed in monospace font
- Standard error (stderr) appears in red
- Output is capped at 10,000 lines in the frontend
You can close the dialog while the script runs — reopening it shows the full accumulated output

INFO

Scripts run as bash subprocesses in the project's repository directory. The CLAUDECODE environment variable is removed for safety.

Cancelling Scripts

To stop a running script, click the cancel button in the output dialog. Stib uses a graceful shutdown process:

SIGTERM is sent to the entire process group
Stib waits up to 5 seconds for the process to exit
If still running, SIGKILL is sent to force termination
The process group is fully cleaned up to prevent orphan processes

Backups

Stib uses SQLite's VACUUM INTO for atomic backups that don't interfere with running agents. Backups capture the complete database state.

Manual Backup

From Settings → Backups:

Click Create Backup to generate a new backup immediately
The backup list shows all available backups with timestamps and sizes
For each backup, you can:
- Download — Save the backup file locally
- Delete — Remove the backup from storage

Backup Providers

Backups can be stored locally or sent to a remote provider:

Local Storage

Setting	Value
Storage location	`data/backups/` directory
Configuration	None required (default)

S3-Compatible Storage

Setting	Description
Endpoint	S3 endpoint URL (e.g., `https://s3.amazonaws.com`)
Bucket	Bucket name
Region	AWS region (e.g., `us-east-1`)
Access Key	AWS access key ID
Secret Key	AWS secret access key (encrypted at rest)
Path Prefix	Optional prefix for backup files in the bucket

Works with AWS S3, MinIO, Backblaze B2, and any S3-compatible service.

WebDAV Storage

Setting	Description
URL	WebDAV server URL
Username	Authentication username
Password	Authentication password (encrypted at rest)

Works with Nextcloud, ownCloud, and any WebDAV-compatible server.

TIP

Use the Test Connection button to verify your provider configuration before saving. S3 secret keys and WebDAV passwords are encrypted at rest using the same AES-256-GCM encryption as API keys.

Periodic Backups

Automate backups with a configurable schedule:

Setting	Options
Enable	Toggle periodic backups on/off
Interval	1 hour, 6 hours, 12 hours, or 24 hours
Retention	1 to 100 backups (oldest are automatically deleted)

The backup scheduler:

Persists configuration in the database
Catches up on missed backups at startup (e.g., if the server was down)
Sends WebSocket events on completion (backup.periodic.completed) or failure (backup.periodic.failed)

Restoring from Backup

WARNING

Restoring a backup replaces the entire database. All current data will be overwritten. Make sure you have a recent backup of the current state before proceeding.

Go to Settings → Backups
Choose a restore source:
- From list — Select an existing backup
- Upload — Upload a .db backup file
Type RESTORE in the confirmation field (safety check)
Click Restore — all active agents are stopped and the database is replaced
Restart the server to complete the restore process

INFO

Backup and restore operations require super admin privileges (or are available when authentication is disabled).

Data Exports

Stib can export your data as structured JSON files, useful for archival, data transfer, or analysis.

Project Export

Export a single project with all its data:

Click the download icon in the project top bar
A JSON file is downloaded: stib-export-{project-name}-{YYYY-MM-DD}.json

Organization Export

Export multiple projects at once:

Open the user menu and select Export Data
A modal appears with checkboxes for each project in the organization
Select or deselect projects as needed
Click Export to download the JSON file

What's Included / Excluded

Category	Included	Excluded
Projects	Name, settings, configuration	—
Boards	All boards with settings	—
Columns	Column configuration, positions	—
Cards	Title, prompt, configuration, status	Runtime fields (claudeSessionId, runningSummary)
Conversations	All agent messages	—
Attachments	Metadata (name, type, size)	Binary file content
Users	—	All user data
Credentials	—	All credentials and tokens
Settings	—	App settings, auth config
Sessions	—	Agent session logs

INFO

Export vs. Backup: Exports produce structured JSON (portable, selective, for archival and transfer). Backups produce a full SQLite database copy (complete, fast restore, for disaster recovery). Use exports for data portability and backups for server recovery.

Next Steps

TIP

Now that you understand credentials, scripts, and backups, explore these related guides:

Authentication — Configure user authentication and OIDC SSO
Configuration — Server configuration and environment variables
API Reference — REST API endpoints for programmatic access

Credentials, Scripts & Backups ​

Credentials ​

Credential Types ​

Adding an API Key ​

Adding an OAuth Profile ​

Credential Assignment ​

Usage Monitoring ​

Verification & Health ​

Managing Credentials ​

Encryption & Security ​

Project Scripts ​

Configuring Scripts ​

Running Scripts ​

Cancelling Scripts ​

Backups ​

Manual Backup ​

Backup Providers ​

Local Storage ​

S3-Compatible Storage ​

WebDAV Storage ​

Periodic Backups ​

Restoring from Backup ​

Data Exports ​

Project Export ​

Organization Export ​

What's Included / Excluded ​

Next Steps ​

Credentials, Scripts & Backups

Credentials

Credential Types

Adding an API Key

Adding an OAuth Profile

Credential Assignment

Usage Monitoring

Verification & Health

Managing Credentials

Encryption & Security

Project Scripts

Configuring Scripts

Running Scripts

Cancelling Scripts

Backups

Manual Backup

Backup Providers

Local Storage

S3-Compatible Storage

WebDAV Storage

Periodic Backups

Restoring from Backup

Data Exports

Project Export

Organization Export

What's Included / Excluded

Next Steps