ArkSpace

<p> <a href="README.zh-CN.md">中文</a> · <a href="INSTALL.md">Install</a> · <a href="docs/architecture.md">Architecture</a> · <a href="CONTRIBUTING.md">Contributing</a> </p>

ArkSpace as a futuristic ark-like workspace containing research, knowledge, workflow, toolbox, planning, and engineering capabilities.

Reusable Agent Skills for web evidence, cited research, browser work, and monitoring—backed by one secure local execution boundary when shared Provider access is required.

ArkSpace gives coding Agents focused operating instructions instead of one oversized prompt. The first release includes five canonical Skills and the arks CLI, which coordinates Provider credentials, multiple-key rotation, fallback, owned remote resources, and machine-readable results.

Start in two minutes

Ask an Agent to install it

Paste this into your coding Agent:

Install ArkSpace from https://github.com/arch3rPro/Ark-Space by following the repository's INSTALL.md. Ask before changing my global packages, Agent configuration, or MCP configuration. Never ask me to paste an API key into this conversation. When credentials are required, stop and ask me to run `arks setup` myself in a trusted local terminal. Verify the CLI, installed Skills, and Provider readiness before declaring success.

Or install it yourself

See the 0.1.5 release notes for features, verification evidence, and qualification limits.

npm install --global @arkspace/cli@latest
npx skills@latest add arch3rPro/Ark-Space

Then run the credential wizard yourself in a trusted local terminal:

arks setup
arks doctor
arks web search "agent skills"

Keep API keys out of Agent chats. arks setup uses hidden terminal input and stores local credentials separately from configuration and state. Environment variables remain available for CI and externally managed secrets.

See INSTALL.md for host-specific installation, verification, update, uninstall, MCP, and credential details. The 0.1.5 release-candidate source adds manual npm CLI update checks and installation; published 0.1.4 does not include the updater, and availability of the candidate package on npm is not implied. Install the CLI with @latest and update Skills separately.

Check and update installed Skills

For Skills installed through the Skills CLI:

npx skills@latest check   # Check for available Skill updates
npx skills@latest update  # Manually update installed Skills

These commands apply to Skills tracked by the installer, not just ArkSpace. Back up local edits before updating; npx may download the tool and write its cache. CLI updates are separate, and native Codex/Claude plugins use their host's plugin update mechanism.

Choose the Skill by outcome

askme is guidance-only: it needs conversational follow-up, with no CLI, network, credentials, or sibling Skills. It can be invoked explicitly or selected by the Agent when a consequential ambiguity or execution mismatch needs resolution. Clear tasks proceed directly; alignment does not add a universal approval step.

See the Skill, Capability, and Provider reference for operation identifiers, Provider coverage, fallback behavior, and resource ownership.

Optional managed WeKnora configuration (0.1.4)

Run arks setup weknora in your trusted terminal to manage its API root, masked key, and optional default knowledge base. Authenticated managed verification, list/detail, and search may target a valid localhost, private, or public address without a CIDR exception. They retain URL and address validation, DNS pinning, TLS verification, redirect refusal, no-proxy transport, deadlines, and response bounds. An explicit request to read the configured instance authorizes that network access; HTTP is supported with an informational plaintext-transport warning. The managed path does not join Web search order or fallback.

A manually supplied WEKNORA_BASE_URL / WEKNORA_API_KEY pair remains independent and needs no CLI. Imports, document/chunk operations, multi-base search, and streamed chat continue using that environment path. See installation and the managed guide.

What the runtime adds

A Skill can remain pure guidance, carry a self-contained script, use an external application, or call a shared ArkSpace capability. arks is required only for the last case.

Agent host
  └─ Agent Skill
      ├─ host tools / Skill-local scripts / external tools
      └─ arks invoke <capability> --input <file>
          ├─ Provider-neutral capability handler
          ├─ Exa / Tavily / Firecrawl / SearXNG adapter
          └─ credentials, key pool, fallback, and owned state

The shared runtime provides:

• Stable machine output: one Protocol v1 JSON envelope on stdout; diagnostics stay on stderr.
• Credential isolation: setup happens in a human-controlled terminal, while config and state retain references and non-secret metadata.
• Multiple-key handling: transactional round-robin selection, cooldown, disable states, and classified fallback.
• Honest remote lifecycle: timeout, cancellation, uncertain acceptance, partial output, and cleanup remain distinct outcomes.
• Owned resources: browser sessions and monitors stay bound to the credential that created them and require confirmation for material side effects.
• One MCP adapter: arks mcp serve exposes the same dispatcher instead of duplicating Provider logic.

Human and machine entry points

Human-facing commands optimize for discovery:

arks provider list
arks web fetch "https://example.com/docs"
arks web crawl "https://docs.example.com" --max-pages 20 --max-depth 2
arks code context "current TypeScript SDK usage"
arks research run "compare current agent research APIs" --depth standard
arks browser open "https://example.com"
arks monitor status <monitor-id>

Skills use the stable machine boundary:

arks invoke web.search --input search-request.json
arks invoke research.run --input research-request.json
arks invoke browser.open --input browser-open-request.json
arks invoke monitor.create --input monitor-create-request.json

Protocol schemas are published under schemas/protocol/v1/.

Installation surfaces

• Portable Skills: compatible filesystem-based hosts can install the canonical skills/ tree with the Agent Skills installer.
• Claude Code plugin: the repository marketplace manifest references canonical Skills directly.
• Codex plugin metadata: .codex-plugin/plugin.json points to the same canonical directory.
• MCP stdio: Claude Code, Codex, and other MCP hosts can register arks mcp serve when tool discovery is useful.

There are no generated plugin mirrors. Routine Skill changes update the canonical source; plugin version metadata changes only during an explicit release.

Security model

• Never enter API keys in an Agent question, chat message, command argument, fixture, or tracked file.
• arks setup writes local keys to the user-level credentials.json file with restrictive permissions where supported.
• Explicit environment variables override locally stored values.
• config.json stores credential references; state.json stores anonymous key IDs and lifecycle metadata.
• Browser and monitor mutations require explicit confirmation; cleanup and uncertain remote outcomes remain visible.

The local credential file contains plaintext secrets and is not an operating-system keychain. Read ADR 0009 and Security Policy before choosing a credential strategy for a managed environment.

Release status and limits

0.1.5 release-candidate changes since 0.1.4 include manual npm CLI updates, improved bounded research evidence review, and Skill icons and invocation policies. See release notes for evidence and qualification limits. The 0.1.4 release added optional managed WeKnora verification and retrieval; see 0.1.4 release notes.

Version 0.1.3 includes keyless SearXNG and a rebuilt Setup TUI. The UI has three focus regions—Top, Menu, Content—cycled with Tab/Shift-Tab. Top Left/Right switches provider; brackets remain an advertised alternate, and Down/Enter enters Content. Menu Up/Down selects Providers, Configuration, Settings, or Exit; Enter opens the function and Right enters Content. Content Left returns to Menu. A primary resource table/list drives page-local actions, with non-focusable hints wrapped below the table; there are no legacy stacked toolbars or nested button subfocus. Enter/e edits, a adds, i shows details, p opens secure preview, and d removes. Editing a stored local key preloads it into a masked draft; Esc restores the field, and Ctrl-S validates before explicit overwrite consent. Adding starts blank; unchanged saves close without writing or replacement consent. Space toggles selected-key enablement; V/v toggles provider enablement; t offers a Cancel-default choice between one normal round-robin pool test (five seconds total) and sequential tests of each configured local key reference (one request per reference, five seconds per key). The latter requires consent for request logging, uses isolated temporary state, skips missing/unusable values without requests, and reports only reference/classified outcomes. It does not change global cursor, health, or configuration, and does not fall back to other keys/providers; Esc stops it. SearXNG retains its keyless instance-pool test. Global order and language remain independent: u/d reorder, Delete removes, I includes with confirmation, and Ctrl-S saves order; language is a plain option list applied with Enter. Forms retain safe in-memory drafts and guarded saves. Selected-key cooldown is a snapshot, not a live countdown. Diagnostic rows are session-only historical results: context switching retains them, while attempted managed writes and normal pool tests clear them; they do not validate externally changed credential values. See ADR 0017 for the current interaction contract and NOTICE.md for reference provenance. Automated Linux PTY qualification uses standard-library Python 3 as a development-only prerequisite, not an end-user CLI dependency. Qualification evidence and caveats are tracked in the priority-one workbench report; human usability, real services, and hosted Windows/macOS terminals remain unqualified.

Build the checkout as described in INSTALL.md, then run node dist/cli/main.js setup (or append exa, tavily, firecrawl, or searxng) without replacing your global installation. Existing credential preview, environment precedence, ownership guards, narrow per-instance CIDR consent, live-test consent, cancellation, and terminal restoration remain as specified in the setup contract.

Current limits:

• Node.js 20 or newer and a local host with shell, network, and persistent user storage are required.
• Exa, Tavily, and Firecrawl operations require the applicable account and may incur Provider charges; SearXNG search instead requires an explicitly configured instance.
• Keyless Exa MCP access and Tavily/Firecrawl OAuth are research topics, not implemented authentication backends.
• Hosted cross-platform and credentialed live-Provider qualification remains part of the post-release backlog.
• This release does not declare replacement cutover of the existing ArkSpace project.

Project guide

Development

git clone https://github.com/arch3rPro/Ark-Space.git
cd Ark-Space
npm install
npm run check

Read CONTRIBUTING.md and AGENTS.md before changing the project. Security reports follow SECURITY.md.

License

ArkSpace is available under the MIT License. External source and attribution notices are recorded in NOTICE.md.