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

Two official templates are available:

Every template includes a pre-configured catalog-info.yaml and is ready to deploy.

Eco App — recommended for most projects

tawa sample my-app --eco-app
cd my-app
pnpm install
tawa dev --offline   # mock services + .env.local generation
pnpm dev             # starts on port 4140

tawa dev --offline provides mock Bio-ID (auto-login), mock Septor, Relay, and Storage so you can develop without any external dependencies.

Static Site

tawa sample my-site --static
cd my-site
pnpm install
pnpm build           # compiles Tailwind CSS
tawa deploy --prod

Add a Git Repo

Pass --git to any scaffold to automatically create a git.insureco.io repo and configure the auto-deploy webhook:

tawa sample my-app --eco-app --git

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-app
  description: My app
  annotations:
    insureco.io/framework: nextjs
spec:
  type: service
  lifecycle: production
  owner: my-org
  auth:
    mode: sso         # auto-provisions Bio-ID OAuth client
  databases:
    - type: mongodb   # auto-provisions MONGODB_URI

metadata.name becomes your service hostname: my-app.tawa.pro (production) or my-app.sandbox.tawa.pro (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

tawa deploy --prod

WARNING: Always use tawa deploy --prod for production deployments. Sandbox deployments trigger real cron jobs and email sends — sandbox isolation controls are not yet in place.

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

Troubleshooting

tawa troubleshoot