Getting Started

Go from zero to your first encrypted secret in 3 minutes. This guide covers installation, first-time setup, storing and retrieving secrets, and optional SSO configuration.

1. Install Arcan

Choose your preferred installation method:

Homebrew (macOS)

brew install arcan

Go Install

go install getarcan.dev/arcan/cmd/arcan@latest

Shell Script

curl -fsSL https://getarcan.dev/install.sh | bash

Docker

docker run -d \
  --name arcan \
  -p 8081:8081 \
  -v arcan-data:/root/.arcan \
  getarcan/arcan server

Build from Source

git clone https://github.com/getarcan/arcan.git
cd arcan
go build -o arcan ./cmd/arcan
./arcan version

Verify the installation:

arcan version
# arcan 0.1.0 (commit: abc1234, built: 2026-04-01T12:00:00Z)

2. Start the Server

Run the server. On first launch, Arcan detects no existing users and starts the interactive setup wizard automatically.

arcan server

Expected output:

  +---------------------------------------------------+
  |  Arcan -- First Time Setup                        |
  +---------------------------------------------------+

  Admin email: [email protected]
  Admin password (min 12 chars): ************
  Confirm password: ************

  > Admin user created
  > API token: arc_7f3a9b2e1c4d...
  > Default realm "default" created

  Save this token -- it won't be shown again.

  Storage : /Users/you/.arcan/data/arcan.db
  Mode    : standalone (SQLite)
  Key     : /Users/you/.arcan/data/master.key
  Port    : 8081
  Starting...
  server starting  addr=https://0.0.0.0:8081  version=0.1.0

What happens automatically:

• A 256-bit AES master key is generated at ~/.arcan/data/master.key
• A self-signed TLS certificate is created via the internal CA
• A SQLite database is initialized at ~/.arcan/data/arcan.db
• A default realm is created for immediate use

Leave this terminal running. Open a new terminal for the next steps.

3. Log In

Save the server URL and API token so the CLI can authenticate:

arcan login --token arc_7f3a9b2e1c4d...

Expected output:

  Testing connection to https://localhost:8081...
  > Logged in successfully
  > Config saved to /Users/you/.arcan/config.json

Or use the interactive prompt:

arcan login
# Server URL [https://localhost:8081]: <enter>
# API token: <paste token>

4. Store Your First Secret

arcan kv set DATABASE_URL "postgres://user:pass@db:5432/myapp"

Expected output:

> Set default/dev/DATABASE_URL

The secret is now encrypted at rest with AES-256-GCM in the default realm, dev environment.

Store a few more:

arcan kv set API_KEY "sk_live_abc123"
arcan kv set REDIS_URL "redis://localhost:6379"

5. Retrieve Secrets

Get a single secret:

arcan kv get DATABASE_URL
# postgres://user:pass@db:5432/myapp

List all secrets in the realm:

arcan kv list

Expected output:

KEY            ENV  VERSION  UPDATED
DATABASE_URL   dev  v1       2026-04-02T10:30:00Z
API_KEY        dev  v1       2026-04-02T10:30:05Z
REDIS_URL      dev  v1       2026-04-02T10:30:10Z

Export as a .env file:

arcan kv export > .env

Inject secrets into a running process:

arcan kv run -- node server.js
# DATABASE_URL, API_KEY, REDIS_URL are now environment variables

6. Organize with Realms and Environments

Realms are security boundaries that isolate secrets, policies, and audit trails. Environments (dev, staging, prod) live within each realm.

# Create a realm for your app
arcan realm create myapp "My Application"

# Store secrets in different environments
arcan kv set DATABASE_URL "sqlite:///dev.db" -r myapp -e dev
arcan kv set DATABASE_URL "postgres://staging-db:5432/app" -r myapp -e staging
arcan kv set DATABASE_URL "postgres://prod-db:5432/app" -r myapp -e prod

# Run with production secrets
arcan kv run -r myapp -e prod -- node server.js

7. Set Up SSO (Optional)

If your team uses an identity provider, configure SSO so members can log in without local passwords.

OIDC (Google, Okta, Azure AD, Auth0, Keycloak)

arcan auth setup --type oidc

The interactive wizard will prompt for:

  SSO Type: oidc

  Available presets:
    1. google        Google Workspace
    2. okta          Okta
    3. azure-ad      Azure Active Directory
    4. auth0         Auth0
    5. keycloak      Keycloak
    6. custom        Custom OIDC Provider

  Select preset [1-6]: 2

  Provider name [okta]: okta
  Issuer URL: https://myorg.okta.com
  Client ID: 0oa1abc2def3ghi4j5k6
  Client Secret: ********
  Redirect URL [https://localhost:8081/api/v1/auth/oidc/okta/callback]: <enter>
  Allowed email domains (comma-separated, blank for any): myorg.com

  > OIDC provider "okta" configured
  > Config saved to /Users/you/.arcan/config.yaml
  > Restart the server or send SIGHUP to apply

Test the configuration:

arcan auth test okta

Expected output:

  Testing OIDC provider "okta"...
  > Discovery URL reachable
  > JWKS endpoint responding
  > Token endpoint configured
  > Provider "okta" is healthy

SAML

arcan auth setup --type saml --name azure \
  --metadata-url https://login.microsoftonline.com/.../federationmetadata/2007-06/federationmetadata.xml \
  --acs-url https://arcan.example.com/api/v1/auth/saml/azure/acs

LDAP

arcan auth setup --type ldap --name corp-ad \
  --ldap-url ldaps://ldap.corp.example.com:636 \
  --bind-dn "CN=arcan,OU=Service Accounts,DC=corp,DC=example,DC=com" \
  --base-dn "DC=corp,DC=example,DC=com" \
  --user-filter "(sAMAccountName={{username}})"

Reload the server to apply SSO changes without downtime:

kill -HUP $(pgrep arcan)

8. Invite Team Members (RBAC)

Arcan uses realm-scoped RBAC with three built-in roles:

Role	Capabilities
admin	Full access: manage realms, secrets, policies, tokens, audit
member	Read/write secrets, list realms, view audit
viewer	Read-only: view secrets, list realms, view audit

Registration is admin-only by default. Create a token for a new team member and bind them to a role:

# Create a scoped token for a team member
arcan token create --name "alice-dev" --scopes read,write

# After they register/login, bind them to a role in a realm
arcan policy bind -r myapp --user-id <alice-user-id> --role member

# Verify the binding
arcan policy list -r myapp

List available roles and their capabilities:

arcan policy roles

Expected output:

  admin
    - realms.manage
    - secrets.read
    - secrets.write
    - secrets.delete
    - policy.manage
    - audit.read
    - tokens.manage

  member
    - secrets.read
    - secrets.write
    - audit.read

  viewer
    - secrets.read
    - audit.read

9. Declarative Secrets (GitOps)

For teams that manage secrets alongside infrastructure code, use YAML files:

# secrets.yaml
realm: myapp
environment: prod
secrets:
  DATABASE_URL: "postgres://user:pass@db:5432/app"
  API_KEY: "sk_live_abc123"

Apply them:

arcan apply -f secrets.yaml

For version control safety, encrypt sensitive values first:

arcan kv encrypt "postgres://user:pass@db:5432/app"
# arcan:v1:a1b2c3d4e5f6...

Then use the encrypted value in YAML:

realm: myapp
environment: prod
secrets:
  DATABASE_URL:
    encrypted_value: "arcan:v1:a1b2c3d4e5f6..."

10. Run Diagnostics

If something goes wrong, run the built-in diagnostics:

arcan doctor

This checks:

• Master key file exists and is valid (32 bytes)
• Encryption round-trip test passes
• Database is accessible and schema is current
• TLS certificate is present and not expired
• CA certificate chain is valid

Next Steps

• Architecture Overview -- understand how Arcan is structured internally
• Engine Standard -- write your own secrets engine plugin
• Threat Model -- security boundaries, trust model, and attack surface
• SSO Guide -- detailed SSO configuration for all providers
• Schema Migrations -- database schema design and migration patterns
• API Error Taxonomy -- error codes and response format