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