Administration

This page covers platform setup, org provisioning, user management, and authentication configuration.

Platform Setup

The recommended way to initialize the platform is via the setup wizard:

astonish setup

The wizard handles backend selection (SQLite or PostgreSQL), database initialization, organization creation, admin account setup, and AI provider configuration in a single interactive flow.

For PostgreSQL deployments, you can also set the DSN via environment variable before running setup:

export ASTONISH_PLATFORM_DSN="postgres://admin:secret@db.acme.corp:5432/astonish_platform"
astonish setup

Platform Initialization (Advanced)

If you need to re-initialize or bootstrap an existing database:

astonish platform init

This creates the platform database schema and runs migrations. The DSN is read from the config file or ASTONISH_PLATFORM_DSN environment variable.

Starting the Platform

After setup, start the daemon:

astonish daemon install    # Register as system service
astonish daemon start      # Start the platform

Studio is available at http://localhost:9393. For debugging or foreground operation:

astonish daemon run        # Run in foreground (useful for debugging)

Other daemon commands:

astonish daemon status     # Check if daemon is running
astonish daemon stop       # Stop the daemon
astonish daemon restart    # Restart the daemon
astonish daemon logs       # View daemon logs
astonish daemon uninstall  # Remove system service

Organization Provisioning

# Create an organization
astonish platform org create --name "Acme Corp" --slug acme

# With an owner assigned
astonish platform org create --name "Acme Corp" --slug acme --owner-email alice@acme.corp

# List all organizations
astonish platform org list

User Management

Inviting Users

# Invite a user to an org
astonish platform org invite --org acme --email bob@acme.corp --role member

# Invite as admin with team assignment
astonish platform org invite --org acme --email alice@acme.corp --role admin --team platform

Managing Users

# List users
astonish platform user list

# Show user details
astonish platform user show <user-id-or-email>

# Disable user access (preserves data, revokes login)
astonish platform user disable <user-id-or-email>

# Re-enable user
astonish platform user enable <user-id-or-email>

# Promote user to platform admin
astonish platform user promote <user-id-or-email>

# Demote from platform admin
astonish platform user demote <user-id-or-email>

# Reset password
astonish platform user set-password <user-id-or-email>

# Delete user
astonish platform user delete <user-id-or-email>

Other Platform Commands

# Generate a JWT secret
astonish platform gen-secret

# Check platform status
astonish platform status

# Issue an API token for a user
astonish platform issue-token --user <email> --org <slug>

# Audit sandbox usage
astonish platform sandbox-audit

Authentication

Built-in Auth

The default mode. Users authenticate with email/password. Passwords are hashed with bcrypt. Sessions use JWTs.

Configured in ~/.config/astonish/config.yaml:

storage:
  auth:
    mode: builtin
    jwt_secret: "your-jwt-secret"   # Generated by 'astonish platform gen-secret'

OIDC Federation

For enterprise environments, federate with any OIDC-compliant provider:

storage:
  auth:
    mode: oidc
    oidc:
      issuer: https://accounts.sap.com
      client_id: $<OIDC_CLIENT_ID>
      client_secret: $<OIDC_CLIENT_SECRET>
      scopes: [openid, email, profile]

Tested providers: SAP IAS, Azure AD, Okta, Google Workspace, Keycloak.

Users are auto-provisioned on first login when their email domain matches an org's allowed domains.

Platform CLI Commands Summary

Command	Description
astonish platform init	Initialize/migrate platform database
astonish platform status	Show platform status
astonish platform gen-secret	Generate a JWT secret
astonish platform org create	Provision new organization
astonish platform org list	List all organizations
astonish platform org invite	Invite user to organization
astonish platform user list	List platform users
astonish platform user show	Show user details
astonish platform user disable	Suspend user access
astonish platform user enable	Restore user access
astonish platform user promote	Promote to platform admin
astonish platform user demote	Demote from platform admin
astonish platform user set-password	Reset user password
astonish platform user delete	Delete user
astonish platform issue-token	Generate API token
astonish platform sandbox-audit	Audit sandbox resources

Next Steps

• Platform Overview — architecture and design decisions
• Cascading Defaults — configuring defaults at each level
• Remote CLI — how users connect to the platform