Documentation Menu

Frequently Asked Questions

General

What is SpecMarket?

SpecMarket is an open marketplace for SaaS-replacement specifications. Engineers publish battle-tested blueprints (specs) for replacing specific SaaS tools. You run a spec with the CLI, an AI coding agent builds the software autonomously, and you own the result. No subscription. No per-seat pricing.

What is a spec?

A spec is a structured directory containing everything an AI coding agent needs to build a specific application: a functional specification (SPEC.md), technology requirements (stdlib/STACK.md), code patterns (stdlib/PATTERNS.md), security requirements (stdlib/SECURITY.md), and machine-evaluable success criteria (SUCCESS_CRITERIA.md). See the Spec Format Reference for the complete schema.

What is a Ralph Loop?

A Ralph Loop is an autonomous agentic coding loop. You feed a spec to an AI agent, the agent reads it, writes code, runs tests, fixes errors, and iterates until all success criteria pass — or it stalls. The name comes from Geoff Huntley’s work on autonomous coding workflows. See What is a Ralph Loop? for a full explanation.

Is this a no-code tool?

No. SpecMarket produces real code — TypeScript, Python, Go, Rust, whatever the spec defines. The output is a standard application you deploy and maintain like any other software. You don’t need to write the code yourself (the AI agent does that), but you need engineering capability to deploy, maintain, and customise the result.

Can I really replace SaaS with this?

For commodity workflows — yes. E-signatures, form builders, scheduling tools, basic CRM, internal dashboards — these are well-understood problems with specs that achieve 80-95% success rates. For tools with deep network effects (Slack), heavy regulatory requirements (certain fintech), or real-time collaboration (Figma) — probably not, and we say so honestly. See The True Cost of SaaS for a framework on evaluating what to replace.

Costs

How much does it cost to run a spec?

API token costs vary by spec complexity:

  • Simple CLI tools: $5-$10
  • Form builders, scheduling tools: $6-$12
  • E-signature applications: $8-$15
  • Full web applications: $15-$50

These are one-time costs. You pay for the API tokens, you get the code, you own it. Every spec on the marketplace shows its average cost across community runs.

What if a run fails? Do I lose the money?

You pay for the API tokens consumed during the run, regardless of outcome. A spec with a 94% success rate across 230 runs means roughly 1 in 17 runs might fail. We recommend budgeting for 1-2 runs on your first attempt. The marketplace shows exact success rates so you can assess the risk before running.

Are there ongoing costs?

Hosting costs if you deploy the application (typically $0-$25/month depending on your setup). Maintenance time of 2-4 hours per quarter for dependency updates. No subscription fees to SpecMarket for running specs.

Is SpecMarket free?

Running specs from the marketplace is free (you pay only your own API token costs). Publishing specs is free. The bounty system involves payments between bounty posters and spec creators — SpecMarket takes a small platform fee on bounty payouts. Managed runs (cloud-hosted spec execution) will be a paid feature when it launches.

Using the CLI

How do I install the CLI?

pnpm add -g specmarket

Requires Node.js 20 or later. See the Getting Started guide for full setup instructions.

Do I need an account?

No. You can run specs without an account. Creating an account (free) lets you submit run telemetry, rate specs, publish your own specs, and claim bounties.

Do I need my own Anthropic API key?

No. Claude Code works with a Claude subscription — no separate API key required. Specs are executed by Claude Code running locally on your machine.

How long does a spec take to run?

Depends on complexity. Simple specs (CLI tools, small libraries) complete in 10-20 minutes. Full web applications take 30-60 minutes. The marketplace shows average build times for each spec.

Can I use models other than Claude?

Currently, the only supported runner is claude-code, which uses Anthropic’s Claude models. You can choose which Claude model to use with the --model flag. Support for additional runners may come in future versions.

What if the run stalls?

The CLI reports exactly where the agent got stuck: which success criteria passed, which failed, and the agent’s last actions. You can retry (agents aren’t deterministic — results vary), try a more capable model, or check the spec’s known issues on the marketplace.

Security

Is it safe to run specs from strangers?

Use the Docker sandbox:

specmarket run @someone/spec-name --sandbox docker

This isolates the build in a container with no access to your host filesystem, credentials, or network (except the Anthropic API). See Security & Trust Model for full details.

What data does SpecMarket collect?

Only if you opt in: spec ID, model used, tokens, cost, time, status, success criteria results, OS, Node version, CLI version. Never source code, file contents, environment variables, or credentials. Telemetry is off by default. See Security & Trust Model.

Can I delete my data?

Yes. specmarket config delete-telemetry removes all run reports associated with your account.

Are specs reviewed before publishing?

Every spec goes through an automated LLM-based security scan that checks for data exfiltration, crypto mining, security disabling, obfuscated payloads, and prompt injection. Community flagging provides an additional layer — 3 flags hide a spec pending admin review.

Creating Specs

How do I publish a spec?

Write your spec following the Spec Format Reference, validate it with specmarket validate ./my-spec, then publish with specmarket publish. The spec goes through a security scan before listing. A full creator guide is coming soon.

Can I earn money from specs?

Yes, through the bounty system. Companies and individuals post bounties for specs that replace specific SaaS tools. Build a spec that meets the bounty criteria, submit it, and earn money when the community validates it. Payouts are handled through Stripe Connect.

What makes a good spec?

From observing community runs, high-success-rate specs share these traits:

  1. Specific technology choices (not “use a framework” but “use Next.js 14 with App Router”)
  2. Machine-evaluable success criteria (pnpm test passes, not “works well”)
  3. Defined code patterns and file structure
  4. Reasonable scope (targeting 80% of a SaaS tool, not 100%)
  5. Explicit error handling instructions

Can I fork and improve someone else’s spec?

Yes. specmarket fork @author/spec-name creates a copy under your account. The fork relationship is tracked — the original author gets attribution, and users can see the lineage. Improving existing specs is encouraged.

Troubleshooting

”Command not found: specmarket”

Make sure pnpm’s global bin directory is in your PATH. Run pnpm bin -g to find the directory, then add it to your shell profile (~/.zshrc or ~/.bashrc).

”Spec validation failed”

Run specmarket validate ./my-spec for specific error details. Common issues: missing required fields in spec.yaml, missing PROMPT.md/SPEC.md/SUCCESS_CRITERIA.md, invalid semver format.

”Rate limit exceeded”

The CLI enforces rate limits: max 10 run submissions per hour. Wait and try again. This protects the platform from abuse.

”Ralph Loop stalled”

The agent couldn’t make progress. Check specmarket report latest for details on which success criteria failed. Options: retry (results vary between runs), use a more capable model (--model claude-opus-4), or check the spec’s marketplace page for known issues.