Skip to content
wfnexus

Quickstart

wfnexus is three binaries:

  • wfx-server is the engine, the API and the UI, all in one binary.
  • wfx is the CLI.
  • wfx-runner is an optional worker for other machines.

With no configuration at all, the server runs on SQLite and a local folder.

  1. Build. You need Go, Node and Task.

    Terminal window
    git clone https://github.com/muthuishere/wfnexus && cd wfnexus
    task build        # bin/wfx-server, bin/wfx, bin/wfx-runner

    task build first builds the UI and stages it, the templates, the skills and registries.json into the server binary with go:embed. A downloaded wfx-server therefore works with nothing beside it.

    You can also build wfx alone with go install github.com/muthuishere/wfnexus/apps/api/cmd/wfx@latest. This does not work for the server, because its embedded UI is staged by the build and is not committed.

  2. Start the server.

    Terminal window
    ./bin/wfx-server          # http://127.0.0.1:8090 — loopback only

    The default is WFX_MODE=local: state goes in SQLite at ~/.local/share/wfnexus/wfnexus.db, and artifacts go in a folder beside it. WFX_MODE=server switches to Postgres and S3/MinIO. WFX_ADDR=:8090 listens on every interface.

    On loopback there is no login: open http://127.0.0.1:8090. Any other bind, including the Docker compose install, requires one. Sign the CLI in once with wfx login --url <host>, then open the UI signed in:

    Terminal window
    wfx ui --url http://localhost:8090   # one-time link, valid 60 seconds, then a session cookie

    The link works once, and no token is ever put in it. For a browser on another machine, the UI’s sign-in card shows a code. Approve it from a signed-in terminal with wfx login --approve <code>. Sign out in the top bar revokes that browser’s token.

  3. Check what is wired.

    Terminal window
    wfx doctor

    doctor prints the default provider, the platform and shell, and every provider and classifier marked ✓ or ✗ with the reason. The reason names a variable, never a value, for example ANTHROPIC_API_KEY is not set. It ends with a list of problems: each one is a step that would fail when it runs. Here is an excerpt from a real machine:

    Default provider opencode  (WFX_DEFAULT_PROVIDER: steps without their own provider run here)
    

    providers (30)
      ✓ claude-cli     cli    /Users/…/.local/bin/claude
      ✓ devin          acp    /opt/homebrew/bin/devin
      ✗ groq           http   openai/gpt-oss-120b  https://api.groq.com/openai/v1
          GROQ_API_KEY is not set
    classifiers (4)
      ✗ jev            openrouter typesafe/jev-1.13  OPENROUTER_API_KEY
      ✓ recorded       static

  4. Do a first run with no model and no key. workflows/mock-demo.yaml runs on the built-in mock provider and stops for a human before its act step, so you can try the approval path for free:

    Terminal window
    wfx run mock-demo -f       # follows the log; pauses before `act`
    wfx approve <run-id>       # or: wfx reject <run-id> -m "why"
    wfx show <run-id>          # the run, step by step

  5. Point it at a real model. Store a key in the encrypted env store (it is never echoed), or use a free model over ACP:

    Terminal window
    wfx env set OPENROUTER_API_KEY      # reads the value without echoing it
    wfx adapters                        # devin, opencode, codex: which are installed
    wfx models opencode-acp --free      # the free models opencode offers, asked live

    See Providers and models.

  6. Give your agent the skills. Claude Code and Codex build workflows through agent skills:

    Terminal window
    wfx install --skills       # every skill into ~/.claude and ~/.agents

    Then ask your agent something like “take this off my plate as a wfnexus workflow”. See Agent skills.

Next

Section titled “Next”