# Get started with Host Little

Host Little hosts GitHub applications and managed PostgreSQL. This guide is for
coding agents helping an owner deploy or operate a project.

Canonical guide: https://hostlittle.com/get-started.md
Human setup and API key settings: https://hostlittle.com/agents
Portal: https://hostlittle.com/portal

## Start here

1. Ask whether the owner wants to deploy a repository or manage an existing project.
2. If needed, have the owner sign in and create an API key at
   https://hostlittle.com/portal/settings/agents. Keep `HOSTLITTLE_AGENT_KEY` in
   the client's private environment or secret store, never in this chat, Git,
   hosted application variables, build inputs, or public `NEXT_PUBLIC_*` values.
3. Read `GET https://hostlittle.com/api/v1/account`, then
   `GET https://hostlittle.com/api/v1/projects`, with
   `Authorization: Bearer $HOSTLITTLE_AGENT_KEY`. Choose the exact project ID;
   do not guess from a similar name or assume cross-workspace access.
   For an MCP-only client, discover tools and begin with `projects_list`; do not
   invent an account tool. The API enforces permissions on every request.
4. Read the project's current deployment and configuration before changing it.
   If the client has no terminal/API tools, guide the owner through the portal
   or a connected coding client; reading this document alone does not grant access.

## Choose a tool

### MCP: local stdio server

Requires Node.js 22 or later and an MCP client that can launch a local process:

```sh
npx --yes https://hostlittle.com/downloads/hostlittle-cli-0.1.0.tgz mcp
```

Configure `HOSTLITTLE_AGENT_KEY` privately in that client's environment. Discover
its tools with `tools/list`. Tools cover project inventory, deployment activity,
attached database metadata, redacted environment reads, permitted environment
updates and redeploy requests, and feature flags.

This is a local stdio server, not a hosted remote MCP URL. ChatGPT/Claude client
capabilities differ; do not invent an HTTP MCP endpoint or imply a vendor partnership.
MCP does not return secret values.

### CLI: local development

```sh
npm install -g https://hostlittle.com/downloads/hostlittle-cli-0.1.0.tgz
hostlittle mcp
hostlittle run --project PROJECT_ID -- npm run dev
hostlittle env pull --project PROJECT_ID --output .env.local
```

Use an actual ID from project inventory. Local environment export requires
`env:local` for that project or Full owner access. `run` injects values into the
child process; `env pull` adds missing values to an ignored, untracked, private
file and preserves existing assignments. Add `.env.local` to `.gitignore` first.
Exports stop on unavailable values unless the owner explicitly requests a partial
export. Avoid printing secrets through application debug logs.

### HTTP API

Base URL: `https://hostlittle.com/api/v1`. Use the same private bearer key.

| Job | Supported route |
| --- | --- |
| Check identity and access | `GET /account` |
| Find owned/authorized projects | `GET /projects` |
| Read deployment activity | `GET /projects/:id/deploys` |
| Read redacted logs | `GET /projects/:id/logs` |
| Read attached database metadata | `GET /projects/:id/databases` |
| Read or update environment variables | `GET /projects/:id/env`, `POST /projects/:id/env` |
| Request redeployment | `POST /projects/:id/redeploy` |
| Read feature availability | `GET /projects/:id/feature-flags` |

Detailed setup: https://hostlittle.com/agents
For environment updates, send `{ "environment": "production", "key": "NAME",
"value": "VALUE", "isSecret": true }`. For redeploys, send
`{ "environment": "production" }`. Supported environments are `production` and
`development`. Start with reads and use the key's granted permissions. Do not
guess additional routes or commands.

## Permissions and configuration

Project-scoped write keys can return `pending_approval` with an approval URL.
Respect that result; do not retry to bypass approval. An enabled autonomous window
or Full owner access permits supported actions within the key's actual scope.
Full owner access covers currently owned workspaces, not the entire platform.

Ordinary environment reads remain redacted. Managed `DATABASE_URL` and
`POSTGRES_URL` aliases are controlled by the database binding, not ordinary env
writes. The authorized CLI local-export path can supply attached database values
for local development. Do not replace or reveal them through normal MCP reads.
Local env edits do not change a deployed app. Build-time/public changes require a
new build; runtime changes need the supported deployment flow.

## Deploy an app or start from a template

Use https://hostlittle.com/get-started to connect a GitHub repository and choose
its production branch. Push application changes to that connected branch.
Follow the deployment to terminal success, verify the deployed revision, and
check the real application; a queued request or successful build alone is not a
successful deployment. Inspect the existing operation before retrying.

Next.js + Postgres starter:
https://github.com/Jamyye/hostlittle-nextjs-postgres-starter

Its demo note is public synthetic data, not an authenticated notes product.
Add authentication/authorization before using customer data. Preserve existing
migrations and data; builds must not require production database credentials.

## Database and domain operations

The portal supports database provisioning, connections, usage, backups and restore
copies, and project domains/settings. Current agent tools expose attached database
metadata; they do not provide general standalone database CRUD, SQL execution,
backup/restore management or domain management. Use the portal for those actions
rather than inventing API/MCP support. Confirm the selected project and current
feature availability. Do not delete resources or overwrite data without the
owner's specific instruction.

Report the project, action, revision/deployment result and any remaining step.
Never report a requested change as completed before its result is verified.