Lokuma Design Agent: Overview & Getting Started

Lokuma Design Agent is a design intelligence layer for AI agents and developer workflows. It turns raw AI outputs into structured, visually refined designs — improving layout, typography, palette, and overall clarity.

Works as a skill / MCP server alongside Claude Code, Cursor, Codex, Lovable, Bolt, and any MCP client — sharing one balance across all of them.

This guide walks through installing Lokuma Agent, setting up your API key, and using it in your workflow.

1. Quick Start

Get Lokuma running in under a minute:

Install Lokuma Agent

Set your API key

After installation, create an API key in the Lokuma Console (see Section 3 below) and export it in your shell:

Then reload your shell or restart your AI tool.

Run your first prompt

Try one of these in your AI agent:

• "Make me a website for people who love skiing in the Alps, using the lokuma skill"
• "Build a simple landing page for a coffee shop"

Lokuma will structure the layout, typography, and visual hierarchy of the generated result.

2. What Lokuma Agent does

Lokuma Agent connects your agents and local environment to Lokuma's design intelligence — enabling your AI workflows to produce structured, high-quality designs.

With Lokuma Agent, you can:

• Connect your AI agent to Lokuma's design intelligence
• Generate structured layouts and pages from AI output
• Improve typography, hierarchy, and visual consistency automatically

Installation details

Run the install command in your terminal:

The script:

• Installs the Lokuma CLI
• Connects your environment to Lokuma Agent
• Enables agent tools in your development workflow

After installation, restart your AI tools (Claude Code, Cursor, Codex, or similar) so Lokuma Agent is properly loaded and recognized.

After installation

Once the CLI is installed, the next step is to authenticate. You'll need:

1. A Lokuma account
2. An API key (created from the Console — see below)
3. Available credits or billing enabled

3. Set up API Keys

API keys let your local environment securely access Lokuma Agent.

Create an API key

1. Open the Agent Console — sign in if prompted.
2. Go to the API Keys page at /console/keys.
3. Click Create API Key, give it a name (e.g. "Claude Code laptop"), and copy the generated key immediately — it's shown only once.
4. Store it in a password manager or your environment configuration.

For security, treat your API key like a password.

Best practices

• Never hardcode keys in source files or public repositories.
• Use environment variables (LOKUMA_API_KEY) so the key isn't in your code.
• Rotate keys if you believe one has been exposed.
• Delete unused keys from the Console — fewer active keys means smaller blast radius.

Recommended setup

Store your API key as an environment variable in your terminal configuration:

Reload your shell (source ~/.zshrc) or restart the terminal session, then verify:

4. Billing & Usage

Lokuma Agent uses pay-as-you-go dollar top-ups — separate from Website Builder's monthly subscription. Open the Billing page to:

• View current dollar balance
• Top up (one-time or auto-refill rule)
• See per-call cost history + top-up history
• Apply promo codes

Welcome credit

New accounts get a $2 welcome credit automatically — enough to feel out the agent before committing to a top-up. Granted at first sign-in; visible on the Billing page balance.

How billing works

Every agent call is metered per request. As you generate or refine designs through the agent, the dollar cost is deducted from your balance in real time — you can see each call's cost on the Billing page log.

Buying credits (top-ups)

Top-up tiers on the Billing page:

• $10 / $20 / $50 / $100
• Custom amount

Balance never expires — bigger top-ups don't burn faster.

Auto-refill

To avoid getting cut off mid-project, set an auto-refill rule on the Billing page:

"When balance drops below $10, top up $10."

The card on file is charged automatically when the threshold hits. You can change the rule or pause auto-refill anytime. Refund: within 14 days of any top-up, unused portion is fully refundable via support@lokuma.ai; after 14 days the balance is non-refundable but never expires.

Promo codes

If you received a promo code during a launch or campaign:

1. Go to /console/billing.
2. Enter the code in the promo-code field.
3. Apply the code before checkout (if supported).

Usage visibility

The Billing page itself shows real-time balance, per-call cost log, and top-up history. Every generation is logged — exactly what each one cost.

5. Supported environments

Lokuma Agent works inside AI-native development environments and MCP-capable AI tools. Once installed and your API key is set, it activates automatically when your agent generates visual output.

Officially supported:

• Claude Code — restart after install; Lokuma appears as an available skill.
• Cursor — restart after install; use Lokuma in agent and Composer modes.
• Codex — install as a skill, restart agent.
• Lovable — connect Lokuma as an MCP server.
• Bolt — connect Lokuma as an MCP server.
• Any MCP client — Lokuma exposes its design intelligence as a standard MCP server, so any client that speaks MCP can call it.

Same API key + same dollar balance across every client — no per-client billing.

For a full walkthrough with real examples, see the Lokuma Design Agent tutorial.

6. Troubleshooting

Install command doesn't run

Check:

• Your terminal has permission to run shell scripts (curl | bash works in your environment).
• Your network connection is stable.
• Your environment supports the required dependencies (Bash 4+, curl).

Retry:

CLI installed but agent doesn't connect

Likely causes:

• API key is missing or invalid (echo $LOKUMA_API_KEY returns empty).
• Billing is not enabled or credits are unavailable.
• Environment variables weren't loaded into the AI tool's environment.
• AI tool wasn't restarted after install.

API key issues

If authentication fails:

• Confirm the key was copied correctly (no trailing whitespace).
• Check whether the key has been revoked from Console → API Keys.
• Generate a new key if needed.

Billing or usage looks incorrect

Go to Console → Billing to check:

• Remaining credits
• Recent usage records
• Any recent purchases or promo-code applications

If something still looks off, contact support@lokuma.ai.

Next steps

• Design Agent Tutorial — full walkthrough with real examples in Claude Code and Cursor.
• Lokuma Website Builder — building a website in-browser instead of via AI workflow? Start here.
• Pricing Plans — manage credits, subscriptions, and billing for both Website Builder and Design Agent.

Frequently Asked Questions

What is the difference between Lokuma Design Agent and Lokuma Website Builder?

Design Agent is a CLI skill / MCP server for developers using AI environments like Claude Code, Cursor, Codex, Lovable, and Bolt — it adds design intelligence to AI-generated layouts. Website Builder is a separate browser-based product for non-developers building complete websites at lokuma.ai/create. Both share the same design intelligence engine and Lokuma account, but billing is independent:

• Design Agent = pay-as-you-go dollar balance (top up at /console/billing).
• Website Builder = monthly credit subscription (see Pricing Plans).

You can use both from the same account; the balances don't share or transfer.

Which AI environments support Lokuma Design Agent?

Claude Code and Cursor are officially supported, plus other environments that allow CLI-based tool extensions. Restart your AI tool after installation so it can recognize Lokuma as an available skill.

How is Design Agent metered?

By dollar cost per call. Every agent invocation, design generation, or refinement deducts from your balance in real time. Monitor balance + per-call log at /console/billing.

Where do I store my API key safely?

Store it as an environment variable (e.g. LOKUMA_API_KEY) in your shell config (~/.zshrc or ~/.bashrc), not in code. Never commit keys to public repositories, and rotate any key you suspect has been exposed. Delete unused keys from the Console.

Do I need an API key to use Lokuma Agent?

Yes. In most agent and API-based workflows, an API key is required to authenticate your environment.

Do I need to top up before I start?

No — every new account gets a $2 welcome credit automatically. That's enough for a few generations to feel out the agent. After that, top up at /console/billing starting at $10 (one-time or set an auto-refill rule).

Can I use Lokuma Agent and Website Builder from the same account?

Yes. Sign in once and the Console shows both products in the left sidebar: DESIGN AGENT (with its own Billing / Usage / API Keys) and WEBSITE BUILDER (with Subscription / Usage / Rewards). They share the same login but each has independent credit allowances and billing.