Best Practices

Ink is designed for AI agents to deploy, observe, and manage production applications. These patterns help you get the most out of agent-driven development.

Give your agent context

The more context you give, the better the result. Be specific about what you want:

// Bad — vague, agent will guess
Build me a website

// Good — specific, agent knows exactly what to build
Build a Next.js landing page for a SaaS product called "Acme".
Use Tailwind CSS for styling. Include a hero section, features grid,
and pricing table. Deploy it to Ink with the service name "acme-landing".

Use environment variables for secrets

Never hardcode API keys, database URLs, or other secrets. Your agent sets environment variables via the create_service or update_service MCP tools — they're encrypted at rest and snapshotted per deployment.

One service per concern

Keep services focused. Your agent can deploy and manage multiple services in a single project:

• A frontend service for the UI
• A backend service for the API
• A database resource for data

This makes each piece independently deployable, scalable, and debuggable. Your agent can read logs and metrics for each service separately.

Let your agent debug

When a deployment fails or an app returns errors, your agent can diagnose the issue through MCP:

1. get_service — read build logs and runtime logs (up to 500 lines)
2. Check error messages in the deployment status
3. Fix the code and redeploy

Your agent doesn't need a dashboard — it reads logs and metrics programmatically.

Use custom domains for production

Default *.ml.ink URLs are great for development. For production, delegate a DNS zone and let your agent assign custom domains. Your agent handles DNS records, TLS certificates, and email configuration — all through MCP tools.

Monitor with metrics

Your agent can check service health through MCP. Metrics include CPU usage, memory usage, and network throughput over configurable time ranges (1 hour, 6 hours, 7 days, 30 days).

If a service is hitting resource limits, your agent can scale it up with update_service.

Organize with projects

Group related services under a single project. Your agent creates projects automatically when deploying. Use descriptive names:

Document your infrastructure for agents

Store your project name and active services in a file your agent reads at the start of every session — CLAUDE.md, AGENT.md, .cursor/rules, or whatever your client supports. This lets agents pick up exactly where you left off without re-discovering your setup.

# Infrastructure

Ink project: customer-portal
Frontend service: customer-portal-web (React, deployed at web.example.com)
Backend service: customer-portal-api (FastAPI, deployed at api.example.com)
Database resource: customer-portal-db (SQLite via Turso)

Without this, your agent has to call list_projects and list_services every session to figure out what exists. With it, the agent already knows the project name, service names, and URLs — and can jump straight into the task.

Choose the right git strategy

Ink supports two git options:

• Ink managed git — your agent creates a repo with create_repo and pushes code directly. No GitHub access required, no OAuth grants, no setup. Great for prototypes, experiments, and AI-generated apps you don't need to maintain.
• Your own GitHub repo — connect a GitHub repository to own the code long-term. You get full version history, pull requests, branch protection, and team collaboration. If you want to review, fork, or continue developing the code your agent wrote, connect GitHub.

Pushing to either option triggers an automatic redeployment. You can also force a redeployment at any time with the update_service MCP tool — useful when you've changed environment variables or want to restart the service without a code change.