clawdforge/clients/cpp/README.md

clawdforge — C++ SDK

Modern C++ client for the clawdforge HTTP API. Wraps claude -p subprocess calls behind a bearer-token-gated REST service.

• C++17 minimum. C++20 unlocks designated initializers in caller code (used in the examples / tests for ergonomics) but the library itself compiles cleanly at C++17.
• libcurl + nlohmann/json. No Boost.
• RAII, move-only Client (one libcurl handle per instance).
• Throwing API; full exception hierarchy under clawdforge::Error.

Install

Option A — FetchContent (drop-in for existing CMake projects)

include(FetchContent)
FetchContent_Declare(clawdforge
    GIT_REPOSITORY https://github.com/Sulkta-Coop/clawdforge.git
    GIT_TAG        main
    SOURCE_SUBDIR  clients/cpp
)
FetchContent_MakeAvailable(clawdforge)

target_link_libraries(my_app PRIVATE clawdforge::clawdforge)

CURL must be available via find_package(CURL REQUIRED). On Debian/Ubuntu: sudo apt install libcurl4-openssl-dev.

Option B — install + find_package

git clone https://github.com/Sulkta-Coop/clawdforge.git
cd clawdforge/clients/cpp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
sudo cmake --install build

Then in your project:

find_package(clawdforge CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE clawdforge::clawdforge)

Quickstart

#include <clawdforge/client.hpp>
#include <iostream>

namespace cf = clawdforge;

int main() {
    cf::Client client{cf::ClientOptions{
        .base_url = "http://localhost:8800",
        .token    = "cf_...",
    }};

    auto h = client.healthz();
    std::cout << "claude_version=" << h.claude_version << "\n";

    auto r = client.run(cf::RunRequest{
        .prompt = R"(Reply with JSON: {"hello":"world"})",
        .model  = "sonnet",
        .timeout_secs = 60,
    });

    if (auto* j = std::get_if<nlohmann::json>(&r.result)) {
        std::cout << j->at("hello").get<std::string>() << "\n";
    } else if (auto* s = std::get_if<std::string>(&r.result)) {
        std::cout << *s << "\n";
    }
}

API

clawdforge::Client (in <clawdforge/client.hpp>):

Method	HTTP	Returns
healthz()	GET /healthz	HealthzResponse
run(req)	POST /run	RunResult
upload_file(path, ttl_secs=0)	POST /files	FileToken
create_token(req)	POST /admin/tokens	AppToken
list_tokens()	GET /admin/tokens	std::vector<AppTokenInfo>
revoke_token(name)	DELETE /admin/tokens/<name>	void

All methods throw on failure. ClientOptions lets you set base_url, token, admin_token, timeout, connect_timeout, user_agent, and insecure_tls.

Errors

clawdforge::Error                  // abstract base, derives from std::runtime_error
├── clawdforge::AuthError          // 401 / 403, or missing token on the client
├── clawdforge::APIError           // any other non-2xx — has status_code() + body()
├── clawdforge::TransportError     // libcurl-level failures
└── clawdforge::ProtocolError      // bad URL, missing fields, malformed JSON

Catch broadly:

try {
    client.run(req);
} catch (const cf::AuthError& e) { /* refresh / abort */ }
  catch (const cf::APIError& e)  { std::cerr << e.status_code() << " " << e.body(); }
  catch (const cf::TransportError& e) { /* retry */ }
  catch (const cf::Error& e) { /* anything else */ }

POST /run returns HTTP 502 on subprocess failure. Surfaced as APIError with status_code() == 502; body() parses as the documented RunFailure shape.

File uploads

auto ft  = client.upload_file("/path/to/recipe.png", /*ttl_secs=*/3600);
auto res = client.run(cf::RunRequest{
    .prompt = "extract recipe data",
    .files  = {ft.file_token},
});

The file is streamed off disk via libcurl's curl_mime_filedata — no in-memory buffering of the payload.

Threading

Client is move-only and not thread-safe. Construct one per worker thread or wrap external accesses in a mutex. Multiple Client instances share the process-wide libcurl global state safely (refcounted internally).

Linking

nlohmann_json is a public dependency of the SDK (used in types.hpp for on-wire structs). Consumers therefore compile against and link nlohmann_json even when only calling, say, healthz(). If you already vendor a different version of nlohmann_json, you'll want to pin a compatible version (3.10+) to avoid ODR drift across the boundary.

This is a known v0.1 limitation. A v0.2 refactor will hide nlohmann behind a thin clawdforge::JsonValue wrapper to drop it from the public ABI.

libcurl is private and not exposed across the public header.

Threat model

The SDK is intended for clawdforge servers that the caller trusts (LAN-deployed, bearer-gated). With that in mind:

• The result field of a POST /run reply is untrusted user-influenced data — it carries Claude's response, which can be shaped by whatever ended up in the prompt. The SDK parses it as JSON via nlohmann::json::parse, which is recursion-based. A pathologically deep object (thousands of nested arrays) could push the stack arbitrarily far before the parser bails. The SDK does not currently apply a max-depth guard. If your threat model includes attacker-controlled prompts, either cap prompt size upstream or pre-validate the response body before letting the SDK parse it.

• TLS verification is on by default. Only disable via ClientOptions::insecure_tls = true for self-signed LAN-internal certs. Bearer tokens are passed via Authorization: Bearer …; libcurl strips this on cross-host redirects automatically (≥ 7.64.0), and the SDK additionally pins MAXREDIRS=5 and REDIR_PROTOCOLS=http,https.

• Bearer tokens never appear in exception messages, log lines, or truncate_for_log output by design. If you observe one, that's a bug — please file an issue.

Build options

Option	Default	Effect
CLAWDFORGE_BUILD_TESTS	ON (top-level), OFF (subdirectory)	doctest-based suite
CLAWDFORGE_BUILD_EXAMPLES	ON (top-level), OFF (subdirectory)	builds clawdforge_basic_example
CLAWDFORGE_WARNINGS_AS_ERRORS	ON	-Werror / /WX on the library target

Development

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build --output-on-failure

The test suite spins up a cpp-httplib mock server in-process — no real clawdforge needed.

Test deps

Dep	Version	Notes
cpp-httplib	0.20.1	Test-only; mock binds to 127.0.0.1:0. Optional backends (OpenSSL / zlib / brotli / zstd) are forced off when fetched.
doctest	2.4.11	Test-only.

Test deps are NOT linked into the shipped clawdforge::clawdforge target.

License

MIT. See LICENSE at the repo root.