Getting Started

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

This displays your full platform identity across both Bio-ID and Forgejo:

ℹ Logged in as Admin User
  Email: [email protected]
  ID:    BIO-E1764642376DFQHMF
  Roles: admin, compliance-officer
  Bio org: InsureCo (insureco)
  Git:   my-user @ git.insureco.io
  Git orgs: insureco, my-team

Already have an account?

tawa login

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:

# Login once with --save to create the credentials file automatically
tawa login --email [email protected] --password 'MyPass!' --save

This writes a YAML file at ~/.tawa/credentials with 0600 permissions (owner-only read/write). You can also create it manually to avoid shell escaping issues — especially useful for passwords containing special characters like ! which cause problems in zsh:

# ~/.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

Choose a template that matches what you are building:

Every template includes a pre-configured catalog-info.yaml. You can also create one manually — see the catalog-info.yaml reference.

4. Configure Your Service

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

Here is a minimal working example for an Express API:

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

To add a database, routes, or dependencies, see the full reference.

5. Run Preflight Checks

Before deploying, validate your configuration:

tawa preflight

Preflight checks for:

• Valid catalog-info.yaml syntax and required fields
• Health endpoint exists at the expected path
• Git remote is accessible (Forgejo or GitHub)
• Framework annotation matches your project

Fix any errors before deploying. Use tawa preflight --json for machine-readable output.

6. Deploy

Deploy to sandbox first to verify everything works:

tawa deploy --watch

When satisfied, deploy to production:

tawa deploy --prod

Using a GitHub Repository

Tawa supports both Forgejo (git.insureco.io) and GitHub as source code hosts. Forgejo repos work out of the box. For GitHub repos, the platform needs a Personal Access Token (PAT) to clone your code during builds.

How it works

When you run tawa deploy, the CLI reads your git remote origin URL and stores it in the builder. On each build, the builder clones your repo server-side. For GitHub repos, the builder automatically converts SSH URLs ([email protected]:org/repo.git) to HTTPS and injects the token.

Setup (one-time, done by platform admin)

1. Create a GitHub PAT at Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Grant Contents: Read-only access to the repositories you want to deploy
3. Add the token to the builder:

   # On the builder server
   echo 'GITHUB_TOKEN=github_pat_...' >> /opt/iec-builder/.env
   pm2 restart iec-builder

For developers

Once the platform admin has configured the GitHub token, deploying a GitHub-hosted project works exactly like a Forgejo project:

cd my-github-project
tawa deploy

The builder handles the SSH-to-HTTPS conversion and token injection automatically. You do not need to change your git remote URL.

7. Verify

# Check deployment status
tawa status

# View recent builds
tawa builds

# Stream live logs
tawa logs

# Open in browser
open https://my-svc.sandbox.tawa.insureco.io

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 (if not present) based on 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

Troubleshooting

If something goes wrong, use the AI-powered troubleshooter:

tawa troubleshoot

Common issues:

Next Steps

• catalog-info.yaml Reference — databases, routes, dependencies, and all configuration options
• Gas & Wallets — understand token economics and the deploy gate
• PlugINS Store — browse available platform services