# Getting started

Canonical URL: https://texttree.ai/en/docs/getting-started/
Markdown URL: https://texttree.ai/en/docs/getting-started.md
Page type: docs
Translation status: approved
Legal status: not_required

## Summary

Run the Astro site and Phoenix control plane locally, then walk the current alpha workflow.

## Source content

# Getting started

TextTree is split into two apps:

- `apps/site` for the public Astro site
- `apps/web` for the Phoenix app, developer API, webhooks, and MCP endpoints

## Local workflow

1. Install Node 22+, Elixir 1.19+, Erlang/OTP 28+, and PostgreSQL.
2. Copy `apps/web/.env.example` to `apps/web/.env.local`.
3. Copy `apps/site/.env.example` to `apps/site/.env.local`.
4. Generate a Proton SMTP Submission token before sending real local email.
5. Run `pnpm setup` from the repo root.
6. Start Astro with `pnpm --dir apps/site dev`.
7. Start Phoenix with `cd apps/web && mix phx.server`.

## Local URLs

- Astro public site: `http://localhost:4321`
- Phoenix app and API: `http://localhost:4001`

## Environment groups

Environment variables are scoped by responsibility:

- Phoenix local runtime: `apps/web/.env.local`
- Astro local public config: `apps/site/.env.local`
- production deploy/admin operations: `devops/env/prod.env.local`
- test deploy/admin operations: `devops/env/test.env.local`

Do not use root env files. Only scoped example files are committed.

## Auth mode

Set `TEXTREE_AUTH_MODE` in the Phoenix runtime environment to choose which
signup and login methods are visible.

| Value | Signup/login UI | Enabled behind the scenes | Email delivery required? | Typical use |
| --- | --- | --- | --- | --- |
| `magic_link_or_ethereum` | Email magic link and Ethereum wallet only. Solana, Google, and email/password are hidden. | Email magic link, email/password, and Ethereum wallet. | Yes, configure SMTP. | Current default launch mode. |
| `wallet_only` | Ethereum and Solana wallet buttons only. Email magic link, Google, and email/password are hidden. | Ethereum and Solana wallet. | No. | Crypto-only launch or unverified email delivery. |
| `wallet_first` | Wallet buttons, Google, email magic link, and email/password. | Wallets, Google, email magic link, and email/password. | Yes, configure SMTP. | Broad auth surface after email and OAuth are verified. |
| `full` | Google, email magic link, email/password, and wallet buttons. | Google, email magic link, email/password, and wallets. | Yes, configure SMTP. | Full browser-auth surface for later launches. |

For any mode that shows email magic links, set `TEXTREE_MAILER_ADAPTER=smtp`
and the `TEXTREE_SMTP_*` variables before launch, then run
`mix textree.email.test recipient@example.com`.

## First-run alpha workflow

Once the stack is up:

1. Sign up or log in through TextTree at `/signup` or `/login`, or create a
   headless agent account with `POST /api/v1/accounts` or `POST /mcp/accounts`.
2. Open `/app`.
3. Create or retrieve a TextTree `txt_...` bearer access token with `messages:write`.
4. Add prepaid SMS balance with a USDC funding invoice.
5. Poll the invoice status until the balance is credited.
6. Confirm the recipient is not under a workspace suppression.
7. Use the TextTree bearer access token against `POST /api/v1/messages`.
8. Poll `GET /api/v1/messages/:id` or inspect `/app` for provider and funding state.

## Programmatic onboarding

The current API exposes account bootstrap and launch setup for authenticated users and agents:

- `POST /api/v1/accounts` for username/password headless account creation
- `POST /mcp/accounts` for the same headless bootstrap over the MCP namespace
- `GET /api/v1/onboarding` with `onboarding:read`
- `POST /api/v1/onboarding/api-key` with `onboarding:write` to issue a scoped `txt_...` bearer token
- `POST /api/v1/onboarding/funding-invoices` with `onboarding:write`
- `GET /api/v1/onboarding/funding-invoices/:id` with `onboarding:read`
- `POST /api/v1/onboarding/branded-request` with `onboarding:write`

Headless bootstrap returns one-time backup codes and a `txt_...` TextTree
bearer token with API/MCP scopes. The same funding status is available to agents through
`onboarding.status`, `onboarding.create_invoice`, and
`onboarding.invoice_status` MCP tools.

## Verification commands

- `pnpm test`
- `pnpm verify`
- `pnpm app:test`
- `pnpm www:check`
- `pnpm www:build`

## What the current alpha guarantees

- stable route namespaces
- Neon-ready Ecto config
- Oban queues for messaging and webhook work
- Phoenix-native auth and local identity normalization
- workspace and campaign suppression enforcement
- provider STOP/opt-out reconciliation into workspace suppressions
- spend authorization before provider execution
- verified messaging and funding webhook ingestion
- MCP execution audits, quotas, and timeout policy

## What is not public yet

The current alpha still keeps some critical setup inside the authenticated app rather than public
API endpoints:

- workspace/campaign suppression management
- spend-limit management
- browser backup-code rotation after initial headless bootstrap