DeepSeek Harness Typert vs Gateway: Which Path to Use?
Typert and API Gateway both “reach a capability from outside,” which makes them look like alternatives. They live at different layers: Typert finds and invokes a capability; Gateway decides which capability is exposed to whom (source). Separate the layers, then choose.
DeepSeek Harness: Two layers: capability call vs gateway exposure
One sentence: Typert is the internal remote-call path, Gateway is the external interface layer. Typert cares about lookup, description, and invocation; Gateway cares about exposure, entry, and boundaries. (source)
Two consequences:
- Typert does not expose — it lets a caller find a capability, not decide who may reach it externally.
- Gateway does not discover — it exposes a chosen capability, not perform lookup for callers.
Mixing them produces “the capability is callable, but external access has no boundary,” or “the gateway exposed it, but callers do not know the shape.” The first is security; the second is contract.
Ask who the caller is. Internal plugins, same process, or controlled processes use Typert; external systems, browsers, or third parties use Gateway or web server routes.
DeepSeek Harness: Typert’s three layers
A Typert call has lookup, descriptor, and call layers, each solving one problem (source):
| Layer | Job | Failure looks like |
|---|---|---|
| lookup | Find a capability by name/id | Not found, wrong name, wrong scope |
| descriptor | Read parameter and result shape | Unknown shape, codec mismatch |
| call | Invoke, stream, cancel | Call failed, stream broke, cancel ignored |
A lookup failure is usually a name or scope problem, not “the capability does not exist.” A descriptor failure is closer to a version mismatch: the caller passes an old shape while the provider changed.
The call layer owns encoding, streaming, and cancellation. Testing only “the call succeeded” misses cancel and stream break, which appear only in production.
Typert’s value is standardizing all three: the caller does not need to know which process hosts the provider, only the capability name and descriptor.
DeepSeek Harness: Gateway exposure and authentication
Gateway’s job is “which door is open,” not “how the capability works.” The official reference describes it as the layer that exposes capabilities as external interfaces (source).
Three questions must be explicit:
- Which capabilities are exposed — not every internal capability should be external; a smaller surface is safer.
- Who may call — where authentication, authorization, rate limits, and audit live.
- How failures return — a uniform error shape that does not leak internals.
Gateway does not carry “security” as a property. Being exposable only means reachable; safety comes from auth, network boundaries, and input validation.
A common mistake is exposing an internal admin capability because “there is auth.” Auth answers “who may call,” not “should this be exposed.” Decide separately.
DeepSeek Harness: Four scenarios
Four scenarios cover most choices; use caller and boundary. The table (source):
| Scenario | Caller | Path |
|---|---|---|
| Same-process plugin calls | Plugin | Direct Context/Service, no Typert |
| Cross-process internal calls | Controlled process | Typert |
| Browser or client calls | Web page | Web server route or Gateway |
| Third-party integration | External service | API Gateway with auth and limits |
The first is over-engineered most often. Same-process plugins already have Service and Registry; adding Typert adds serialization and failure surface without benefit.
The second is Typert’s home: callers need capability-name lookup without binding to a process or implementation. The third leans HTTP routing; Typert’s descriptor is not required. The fourth needs Gateway exposure and governance.
Choose caller, then boundary, then protocol. Reversing the order produces “using Typert because it exists.”
DeepSeek Harness: Permissions and resources
Both paths must answer “who is calling and what may they touch,” but at different points. Typert permissions usually live at registration and invocation; Gateway permissions at entry and exposure (source).
Three boundaries:
- Capability-level permission — whether a capability may be called remotely at all.
- Caller identity — who is calling and whether they are allowed.
- Resource scope — which files, sessions, or workspaces the call may reach.
Typert callers may be internal and relatively trusted, but “internal” does not mean unlimited. Gateway callers may be untrusted; input validation and rate limits must be front-loaded.
A rule: make permission decisions closest to the resource, and keep only coarse checks at the exposure layer. Fine-grained checks in both layers drift; checks in only one layer can be bypassed.
DeepSeek Harness: Verify both paths
Run the same capability through both paths and compare. Four steps (source):
- Typert call — lookup by name, read descriptor, invoke; then test cancel and a broken stream.
- Gateway call — call the same capability externally; confirm auth, limits, and error shape.
- Permission comparison — is the same caller allowed the same thing on both paths, with no bypass?
- Failure comparison — missing capability, bad arguments, and timeout return explainable results on both sides.
Four steps show what each path adds and omits. Testing only the happy path usually defers the choice problem to production.
The existing develop-typert-rpc covers lookup/descriptor/call, dsh-api-gateway-explained covers Gateway exposure, and develop-web-server-routes covers HTTP routes; this article covers the choice. Caller first, layer second.
FAQ
DeepSeek Harness Typert handles capability lookup, description, and invocation; API Gateway exposes chosen capabilities to external callers. Typert is the internal call path, Gateway the external interface.
Use DeepSeek Harness Typert when callers need capability-name lookup, descriptors, and streaming; a fixed HTTP endpoint called by path fits Gateway or a web server route.
DeepSeek Harness Gateway owns exposure and call boundaries, but authentication still depends on deployment configuration. Being exposed does not mean being safe.
DeepSeek Harness Typert lookup can cross process boundaries, but crossing machines also needs connection and transport setup. Check Gateway, web server, and network boundaries too.
Related Terms
- Typert
- Typert is the DeepSeek Harness capability remote-call mechanism with lookup, descriptor, and call layers, used to address and invoke a remote implementation.— DeepSeek Harness reference - Typert
- API Gateway
- API Gateway is the DeepSeek Harness layer that exposes capabilities as external interfaces, owning entry, exposure, and call boundaries.— DeepSeek Harness reference - API Gateway
- lookup
- Lookup is the first Typert layer: finding a callable object by capability name or identifier.— DeepSeek Harness reference - Typert
- descriptor
- A descriptor is the Typert description layer, stating parameters, results, and encoding so a caller knows how to invoke the capability.— DeepSeek Harness reference - Typert
Sources
- DeepSeek Harness reference - Typert· deepseek-harness
- DeepSeek Harness reference - API Gateway· deepseek-harness