Getting Started

Go from zero to deployed in under 5 minutes. Install the CLI, create an account, scaffold a project, and deploy it to the Tawa platform.

1. Install the CLI

npm install -g tawa

Verify the installation:

tawa --version

2. Create an Account

tawa login

This opens your browser to Bio-ID where you can sign up or log in. On first registration the platform automatically:

• Creates your user identity (Bio-ID)
• Creates an organization for you
• Provisions a wallet with 50,000 free intro tokens

Confirm you are authenticated:

tawa whoami

Already have an account?

For CI pipelines or AI coding agents (Claude, Cursor, etc.) that cannot open a browser, use stored credentials. The --save flag persists your email and password so the CLI can re-authenticate without a browser:

tawa login --email [email protected] --password 'MyPass!' --save

This writes a YAML file at ~/.tawa/credentials with 0600 permissions. You can also create it manually — especially useful for passwords containing special characters:

# ~/.tawa/credentials (YAML format, 0600 permissions)
email: [email protected]
password: "MyPass!"

The CLI resolves credentials in this priority order:

1. CLI flags — --email and --password passed directly
2. Environment variables — TAWA_EMAIL and TAWA_PASSWORD
3. Stored credentials file — ~/.tawa/credentials

3. Scaffold a Project

Every template includes a pre-configured catalog-info.yaml.

4. Configure Your Service

Open catalog-info.yaml. This is the single source of truth for how the builder deploys your service.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-svc
  description: My API service
  annotations:
    insureco.io/framework: express
spec:
  type: service
  lifecycle: production
  owner: my-org

metadata.name becomes your service hostname: my-svc.tawa.insureco.io (production) or my-svc.sandbox.tawa.insureco.io (sandbox).

5. Run Preflight Checks

tawa preflight

Validates catalog-info.yaml syntax, health endpoint, git remote, and framework annotation. Fix any errors before deploying.

6. Deploy

# Deploy to sandbox first
tawa deploy --watch

# Deploy to production when ready
tawa deploy --prod

7. Verify

tawa status    # deployment status
tawa builds    # recent builds
tawa logs      # stream live logs

What Happens During Deploy

When you run tawa deploy, the builder automatically:

1. Clones your repo at the current commit
2. Parses catalog-info.yaml
3. Checks the deploy gate (wallet reserve)
4. Generates a Dockerfile from your framework
5. Builds and pushes the Docker image
6. Provisions databases and creates K8s secrets
7. Resolves internal dependencies (service discovery URLs)
8. Provisions an OAuth client via Bio-ID
9. Deploys via Helm to Kubernetes
10. Registers the service and routes in Koko
11. Configures DNS via Cloudflare

GitHub Repositories

Tawa supports both Forgejo (git.insureco.io) and GitHub. For GitHub repos, the platform uses a PAT configured by your admin to clone during builds. Once configured, deploying a GitHub project works identically to Forgejo:

cd my-github-project
tawa deploy

Troubleshooting

tawa troubleshoot