DEV Community: Jorge Peraza

Stop Prompting, Start Pairing: How to Actually Get Better at Code by Working With AI Agents

Jorge Peraza — Wed, 16 Sep 2026 23:45:44 +0000

I've been writing code for more than 20 years: PHP, Drupal, TypeScript, cloud infrastructure, and now LLM serving for an agentic IDE I'm building. Over the last year of working with coding agents every day, I've seen developers split into two groups:

Developers who got sharper. They understand more languages, make better architecture decisions, and review code faster.
Developers who got rusty. They ship more code than ever, but they couldn't explain half of it without the agent open. The tool isn't the difference. Both groups use the same agents. The difference is what they delegate.

The trap: delegating the thinking

The default loop looks like this:

prompt → accept → run → "works" → ship

It feels productive, and in the short term it is. But this loop trains you in only one thing: writing prompts. You get output without gaining skill. Six months later, you're faster at producing code and slower at understanding it.

The fix isn't to stop using agents. It's to change the relationship. Treat the agent as three things at once:

A senior pair programmer who challenges your decisions
A rubber duck that talks back when you need to think out loud
A student you have to review and correct Here are the practices that made me better, not just faster.

1. Design first, and make the agent argue with you

Before any code, ask for options instead of an implementation:

I need to add multi-tenant support to this service.
Don't write code yet. Give me 3 architectural approaches
(e.g., shared schema, schema-per-tenant, database-per-tenant),
with trade-offs in cost, isolation, migrations, and operational
complexity. Then ask me which one I'd pick and why.

Then you choose, and you write down why. Now you're practicing the most valuable skill in the job, making architecture decisions under trade-offs, with an expert opponent available 24/7.

Bonus: save that reasoning as an ADR (Architecture Decision Record). Future you, and future agents, will thank you.

2. "Attempt first" for anything you want to learn

For code you just need done, let the agent write it. For code in an area you want to master, write it yourself first, then ask for a review:

Here's my implementation. Review it like a strict senior engineer.
Point out bugs, non-idiomatic code, performance issues, and
edge cases I missed. Don't rewrite it — explain each issue
and let me fix it.

The line "don't rewrite it" matters. If the agent fixes the issue, you learn nothing. If you fix it, you remember it.

3. The "explain it back" rule

My rule before merging any agent-generated code: I must be able to explain every line. If I can't, that's not a reason to trust it. It's a gap in what I know.

When I hit a line I don't fully understand, I flip the roles:

Don't explain this code to me. Quiz me on it.
Ask me 5 questions about what this function does,
why it's written this way, and what breaks if we change it.
Tell me which answers are wrong.

Being quizzed exposes gaps much faster than reading an explanation.

4. Learn new languages by porting code you already know

The fastest way I've found to learn a new language with an agent is to port something you already understand deeply.

Take a small module you wrote in your main language (for me, PHP) and rewrite it yourself in the target language (Go, Rust, whatever). Then ask:

I ported this PHP class to Go. Compare both versions.
Where is my Go code "PHP written in Go syntax"?
Show me the idiomatic Go approach for each case and explain
the language concept behind it (interfaces, error handling,
ownership, concurrency, etc.).

Because you already know the domain logic, all of your attention goes to the language itself: its idioms, its type system, its way of handling errors. You learn the language from your own mistakes instead of tutorial examples.

5. Always ask for the "why" and a source you can verify

Agents are confident even when they're wrong. Turn that into a learning habit:

Why is this the correct approach? Point me to the relevant
documentation section, RFC, or language spec so I can verify it.

Then actually open the source. Half the time you'll learn something the agent didn't mention. The other half, you'll catch it being wrong, and that teaches you even more.

6. Break things on purpose

This is my favorite one. Use the agent to create debugging exercises from your own codebase:

Introduce one subtle bug into this module — something that
passes a quick review but fails in production (race condition,
off-by-one, timezone, null handling). Don't tell me where.
Give me only the symptom a user would report.

Then hunt it down without help. It's like a debugging gym built from your own real code. You can also have the agent write failing tests and make them pass yourself.

7. Architecture katas: let the agent be the chaotic stakeholder

Designs look great until the requirements change. So simulate the change:

Here's my design for an order system. Act as a product manager
who changes requirements every round. Give me one new requirement
at a time (multi-currency, partial refunds, 10x traffic,
GDPR deletion...). After each one, ask me what changes in my design.
Tell me when my design starts to break.

After five rounds, you'll know where your design is fragile, and why patterns like event sourcing, CQRS, or hexagonal architecture exist. You'll understand them from experience, not from a blog post.

8. Review the agent like you'd review a junior, and keep a log

Treat every agent PR as a pull request from a talented junior developer: read it, question it, request changes.

Then keep a simple "agent mistakes log":

Date	Mistake	Why it was wrong	Pattern to remember
09/12	N+1 queries in listing	Lazy loading inside loop	Eager-load relations in list views
09/14	Swallowed exception	Empty catch block	Never catch without logging or rethrowing

After a month, this log becomes your personal list of anti-patterns. The agent's mistakes turn into your expertise.

9. Write your standards down, because it forces you to know them

Most agent tools support a project rules file (for example AGENTS.md, CLAUDE.md, or similar) where you describe conventions, architecture, and boundaries.

Writing that file is a surprisingly hard exercise. You have to spell out things you've only ever "felt":

Why is the domain layer separate from the infrastructure layer?
When do we use a queue versus a synchronous call?
What does "done" mean in this codebase? If you can't write your architecture down clearly, you don't understand it clearly yet. The agent just gave you a reason to find out.

A simple weekly routine

Daily: Apply the "explain it back" rule to every merged PR.
Twice a week: Write one feature yourself first, then get an agent review.
Weekly: Do one bug hunt (practice 6) or one architecture kata (practice 7).
Monthly: Review your mistakes log and update your rules file. It adds maybe 2 to 3 hours a week. In return, you grow as an engineer instead of just getting faster at typing prompts.

How to know if you're learning or just outsourcing

Ask yourself honestly:

Could I rebuild last week's feature without the agent, even if it took longer?
Do I catch the agent's mistakes more often than I did three months ago?
Can I explain the trade-offs behind our current architecture?
Am I comfortable reading code in a language I didn't know six months ago? If the answers are "yes," the agent is making you better. If they're "no," you're renting skill instead of building it.

Improve together

Agents aren't going away, and they'll keep getting better. The developers who thrive won't be the ones who write the best prompts. They'll be the ones who use every interaction as a chance to learn, and who can still think clearly when the agent is wrong.

Don't just give the agent instructions. Grow alongside it.

What's one thing an AI agent taught you that actually stuck? Tell me in the comments. I'd love to build a list of learning techniques together.

Your AI Coding Agent Shouldn't Live on Your Laptop

Jorge Peraza — Mon, 14 Sep 2026 00:47:19 +0000

Every AI coding tool I have used makes the same assumption: the code is on the laptop you are sitting at.

That is true for maybe half of what an engineering team actually does. The rest happens on a dev box, in CI, on a staging environment, or on a build machine that has the toolchain your laptop does not.

We just shipped the MonkeysCode Code Agent, a desktop app for running coding agents across projects without an editor in the way. The most interesting part of it is not the agent loop. It is where the agent is allowed to run.

Four execution backends

The agent can execute against any of these, and you pick per workspace.

Local. Your machine. Full capability, including semantic search against a local index and interactive shell sessions.

SSH. A remote development box. Every command is translated and executed there, not here. This is the one nobody else offers, and it is the one I use most.

Cloud. A managed container workspace, sandboxed by default.

Remote control. A peer machine over WebSocket, running a remote host agent. A build server, a test rig, a colleague's environment.

Each backend declares its real capabilities honestly. Semantic search is not available over SSH, so the agent's system prompt says so and the UI adapts. It is not allowed to attempt something that will fail and then improvise around the error.

That last detail matters more than it sounds. A lot of agent frustration comes from the model confidently trying something the environment cannot do, failing, and then trying three more things. Telling it the truth up front is cheaper than letting it discover the constraint.

What this looks like for DevOps

Here is the part I think is genuinely underexplored in this category.

CI that fixes itself

The CLI runs the same engine headless, with structured output and real exit codes.

- name: Attempt automated fix
  if: failure()
  run: |
    mcode -p "The test suite failed. Read the output, find the cause, fix it." \
          --output json \
          --permission-mode accept-edits > result.json
    echo "exit=$?"

Because every run is test-gated, a change that does not make the suite green never gets applied. The agent either produces a working fix or it produces nothing. There is no middle state where it commits something plausible and moves on.

That is what makes this usable unattended. Not the model quality, the guardrail.

Scheduled maintenance

Background and scheduled runs mean the boring recurring work can happen without a human starting it.

Every Monday 06:00
  → Update dependencies, run the suite, open a PR if green
Every night
  → Generate tests for files changed in the last 24h
Every deploy
  → Check the changelog matches what actually shipped

Each one produces a signed record and a diff you review before merging. It is not autonomous merging, it is autonomous preparation.

Agents on the machine that has the toolchain

This is the SSH case and it comes up constantly.

Your laptop is macOS on ARM. Production is Linux on x86. The build needs a GPU you do not have, or a database that only exists on the dev box, or a proprietary compiler your security team will not license per-seat.

Point the agent at the machine where those things live. It reads the real filesystem, runs the real build, sees the real errors.

mcode --backend ssh --host devbox-3 \
      -p "The nightly build is failing on the arm64 target. Diagnose it."

No syncing, no containerising your dev environment, no reproducing production locally.

Many agents, many projects

The desktop app orchestrates parallel runs across independent projects, each in an isolated workspace. A mission board shows what every agent is doing, an inbox collects the ones waiting on a decision, and you review a signed diff and test report before anything merges.

For anyone maintaining several services, this is the difference between an agent being a tool you use and an agent being work that happens.

The guardrails, because autonomy without them is a liability

Four permission modes, and you switch with a keystroke.

Mode	Reads	Edits	Runs commands
Plan	yes	no	no
Ask	yes	on approval	on approval
Accept edits	yes	automatic	on approval
Auto	yes	automatic	automatic

Note that edit permission and command permission are deliberately separate. In practice people trust an agent to modify a file long before they trust it to run something in their shell. Bundling those into one autonomy slider was a mistake we made early and corrected.

Auto mode is only available inside a sandbox. Not as a policy, as an enforced constraint. Seatbelt on macOS, bubblewrap on Linux, AppContainer on Windows.

Two engineering details worth stealing

We did not build undo on git stash

Every file the agent touches is snapshotted before its first mutation, so you can revert one file or an entire run.

The obvious implementation is git stash push -u. One command, already there, works.

It also destroys your own uncommitted work.

Think about the actual scenario. You have half-finished changes in your tree. You ask an agent to do something unrelated. You do not like the result and you revert. With git stash, your half-finished changes went with it.

So we built a separate snapshot store. Pre-mutation capture per file, selective revert, workspace-scoped so it cannot reach into another project, and honest about limits: a recursive directory delete is flagged as unrevertable rather than silently skipped.

More work than one git command. But an undo feature that occasionally destroys your work is not an undo feature.

Diagnostics report only what the agent broke

After edits, the agent runs your project's type-checker or linter.

The important part is that it captures a baseline at run start and reports only what is new. If your codebase already has 400 warnings, you do not get 400 warnings. You get the ones it just introduced.

Anyone who has introduced a linter to a legacy codebase knows why this matters. Signal drowns in noise, people stop reading it, and the tool stops working. A verification step that produces noise is the same as no verification step.

It also detects the right checker per language, scopes to affected packages in a monorepo rather than checking everything, and retries once on transient failures so a mid-build state does not report a false problem.

Research that outlives the session

One more thing that does not exist elsewhere as far as I know.

Some work is not a task. It is a question you chase across days. A performance regression nobody can reproduce. A migration you are scoping. A bug that only appears under load. That is a dozen runs across a week, and by Thursday you have forgotten what you ruled out on Monday.

Investigations are long-lived threads scoped to a project. Runs link to them, findings accumulate, and the output is real markdown under .monkeyscode/docs/ in your repository. Git-tracked. Editable in any editor. Reviewable in a pull request.

Not locked in an application database that dies with the tool. If your work lives inside a vendor's storage, you do not own it.

On the model

The agent runs on Capuchin, which we train and serve ourselves, or on Claude, Gemini, ChatGPT, or a model on your own hardware. Switching is a setting.

Capuchin Reason scores 62.1% on SWE-bench Pro. Claude Opus, the current leader, scores 64.3%. We are 2.2 points behind, measured on our own production endpoint at the same quantization and context configuration we actually serve, with the methodology published.

The number I find more informative: in production, 92.7% of requests run on Capuchin rather than on a frontier model, even though every user can switch with one setting. For most daily work the 2.2 points are not something you feel.

Owning the model is also why we can support the ones we do not own. Capuchin is cheap enough for us to serve that we can include frontier allowances in the plan and support local models we earn nothing from.

What is not finished

Semantic search only works on the local backend. Over SSH or against a cloud container you get grep and file operations, not vector search. The agent is told this explicitly rather than being allowed to try and fail, but it is a real limitation.

We have not published a cost-per-task figure. Cursor has. We should, and we will, once the measurement is standardised.

The CLI is shipping shortly rather than shipped.

We are pre-1.0 and say so.

Try it

The Code Agent and the IDE are both included in every plan, including the free tier with your own API keys. Thirty days of unlimited Capuchin, no credit card.

👉 monkeyscode.com/code-agent

If you try it, I would rather hear what broke than get a signup. Comments are open and I read all of them, particularly if you have opinions about the SSH backend, which is the part I am least sure we have got right.

Meet Capuchin AI: Fast, Reasoning, and Not the Only Option

Jorge Peraza — Wed, 29 Jul 2026 01:46:28 +0000

Capuchin is the AI that powers MonkeysCode by default. This post is about what it actually does, how it's served, and, since we've gotten this question a lot, what it isn't.

Two modes, one model

Coding tasks aren't uniform. Autocomplete and small edits need to feel instant. Planning a multi-file refactor or chasing a gnarly bug benefits from actually thinking it through. Most tools pick one tradeoff and apply it everywhere. Capuchin doesn't:

Capuchin Flash. Thinking off, sub-second responses. This is the 80% of coding work: completions, small edits, quick questions.
Capuchin Reason. Step-by-step reasoning, budgeted so "thinking" never turns into "spinning." This is the 20% that's actually hard: multi-file plans, debugging, tradeoffs. MonkeysCode routes between them automatically based on the task, or you can pin one yourself. The point isn't "slow but smart" vs "fast but dumb." It's picking the right tool per step, inside a single session.

Why we can afford to include unlimited usage

The honest answer is efficiency. Capuchin is built to activate only a fraction of its total capacity per token. The architecture spends its weights on software-engineering tasks specifically, rather than spreading capacity across everything a general chat model tries to do. That's what makes it both sharper on real coding work and cheap enough to serve that we can bundle generous usage into a subscription instead of metering every token.

Practically, that shows up as:

Speculative decoding and caching keep response times low even under load
A fair-use ceiling, not literal infinity. "Unlimited" is generous, not unbounded, so the economics stay sane for everyone ## Built to use tools, not just talk about them

Capuchin is tuned specifically for agentic work: it calls your terminal, git, test runner, browser, and MCP servers and uses the results accurately across long sessions, the kind of 20-30-tool-call runs that real refactors actually take, not a single-shot completion. It plans before it acts, executes across files in parallel, and runs your tests before handing back. If something fails, it sees the failure and fixes it rather than reporting success prematurely.

It's also polyglot by design, strong across Python, JavaScript/TypeScript, Go, Rust, Java, and more, because most of us aren't working in a single language, and a model that's only good at one is a model you'll outgrow.

What it is not: a local model

This is worth being precise about, because we've seen the confusion. Capuchin is a managed cloud service, the same delivery model as Claude, ChatGPT, or Codex. It is not something you download and run on your laptop.

If you need fully offline or air-gapped work, that's a real, fully supported path in MonkeysCode. It's just a different one: point the IDE at your own model, local (Ollama, llama.cpp, vLLM) or on your own server. Capuchin is the managed default; your own model is the offline path. Two clean, non-overlapping stories, not one confused one.

How it gets better

We start from a strong open foundation and specialize it hard for real software-engineering work inside MonkeysCode, rather than training something narrow from scratch. Improvement after that is:

Opt-in only. Free, Pro, and Team users choose whether usage signals contribute to improving the model. The default is off.
Never from enterprise, self-hosted, or air-gapped installs. No exceptions, regardless of any general opt-in setting.
Signal over source. Where opt-in is given, we prefer derived signals (was the edit kept? did tests pass?) over retaining raw code.
Gated releases. Every new checkpoint has to beat the current one on our internal benchmark before it ships. No regressions allowed through. ## Try it

Capuchin is included with unlimited usage on every paid MonkeysCode plan, and free to try for a month during our founding-user promo.

👉 monkeyscode.com/promo

If you've got questions about the Flash/Reason routing, the fair-use design, or where the local/managed line actually sits, ask away in the comments. Happy to get into the weeds.

Authentication with MonkeysLegion 2.0 + Next.js / React

Jorge Peraza — Fri, 08 May 2026 02:58:20 +0000

A complete guide to implementing JWT-based registration, login, session persistence, and token refresh using the MonkeysLegion v2 API with a Next.js (or React) frontend.

API Endpoints Overview
Backend Setup (MonkeysLegion)
Frontend: API Client
Frontend: Auth Context Provider
Frontend: Register Page
Frontend: Login Page
Frontend: Protected Routes
Token Refresh Flow
Common Issues & Solutions

API Endpoints Overview

MonkeysLegion v2 exposes the following auth endpoints under the /api/v2/auth prefix:

Method	Endpoint	Auth	Description
`POST`	`/auth/register`	No	Create a new user + company
`POST`	`/auth/login`	No	Authenticate and get JWT tokens
`POST`	`/auth/refresh`	No	Exchange refresh token for new access token
`GET`	`/auth/me`	Yes	Get authenticated user profile
`POST`	`/auth/logout`	Yes	Invalidate tokens
`POST`	`/auth/forgot-password`	No	Request password reset

Response Shapes

Login Response — POST /auth/login

{
  "data": {
    "access_token": "eyJ0eXAiOiJKV1Q...",
    "refresh_token": "eyJ0eXAiOiJKV1Q...",
    "token_type": "Bearer",
    "expires_in": 1800,
    "user": {
      "id": 1,
      "email": "user@example.com",
      "full_name": "John Doe"
    }
  }
}

Register Response — POST /auth/register (HTTP 201)

{
  "data": {
    "message": "Registration successful",
    "user": {
      "id": 1,
      "email": "user@example.com",
      "full_name": "John Doe"
    },
    "company": {
      "hash": "abc123",
      "name": "Acme Inc."
    },
    "access_token": "eyJ0eXAiOiJKV1Q...",
    "refresh_token": "eyJ0eXAiOiJKV1Q...",
    "token_type": "Bearer",
    "expires_in": 1800
  }
}

Me Response — GET /auth/me

{
  "data": {
    "id": 1,
    "email": "user@example.com",
    "full_name": "John Doe",
    "phone": null,
    "timezone": "UTC",
    "status": "active",
    "verified": false,
    "two_factor": false,
    "created_at": "2026-05-08T01:25:23+00:00"
  }
}

Backend Setup (MonkeysLegion)

1. Install the Framework

composer require monkeyscloud/monkeyslegion:^2.0.8

Important: Version 2.0.8+ is required. Earlier versions have a bug in DatabaseUserProvider where typed properties (DateTimeImmutable, int, bool) throw TypeError during hydration from raw PDO strings.

2. Entity — `app/Entity/User.php`

<?php
declare(strict_types=1);

namespace App\Entity;

use MonkeysLegion\Auth\Contract\AuthenticatableInterface;
use MonkeysLegion\Query\Attribute\{Entity, Field, Id, Timestamps, Hidden, Fillable};

#[Entity(table: 'users')]
#[Timestamps]
class User implements AuthenticatableInterface
{
    #[Id]
    public private(set) int $id;

    #[Field(type: 'string', length: 255, unique: true)]
    #[Fillable]
    public string $email;

    #[Field(type: 'string', length: 255)]
    #[Fillable]
    public string $full_name;

    #[Field(type: 'string', length: 255)]
    #[Hidden]
    public string $password_hash;

    #[Field(type: 'integer', default: 1)]
    public int $token_version = 1;

    #[Field(type: 'datetime')]
    public private(set) \DateTimeImmutable $created_at;

    #[Field(type: 'datetime')]
    public private(set) \DateTimeImmutable $updated_at;

    // ── AuthenticatableInterface ──
    public function getAuthIdentifier(): int { return $this->id; }
    public function getAuthPassword(): string { return $this->password_hash; }
}

3. Controller — `app/Controller/Api/AuthController.php`

<?php
declare(strict_types=1);

namespace App\Controller\Api;

use App\Service\AuthService;
use MonkeysLegion\Http\Attribute\{Route, Prefix, Throttle, Authenticated};
use MonkeysLegion\Http\Message\Response;
use Psr\Http\Message\ServerRequestInterface;

#[Prefix('/api/v2/auth')]
class AuthController
{
    public function __construct(
        private readonly AuthService $auth,
    ) {}

    #[Route('POST', '/login', name: 'auth.login')]
    #[Throttle(max: 5, per: 60)]
    public function login(ServerRequestInterface $request): Response
    {
        $body = json_decode((string) $request->getBody(), true) ?? [];

        if (empty($body['email']) || empty($body['password'])) {
            return Response::json(['error' => 'Missing credentials'], 400);
        }

        $result = $this->auth->login($body['email'], $body['password']);

        if ($result === null) {
            return Response::json(['error' => 'Invalid credentials'], 401);
        }

        return Response::json([
            'data' => [
                'access_token'  => $result['access_token'],
                'refresh_token' => $result['refresh_token'],
                'token_type'    => 'Bearer',
                'expires_in'    => $result['expires_in'],
                'user' => [
                    'id'        => $result['user']->id,
                    'email'     => $result['user']->email,
                    'full_name' => $result['user']->full_name,
                ],
            ],
        ]);
    }

    #[Route('POST', '/register', name: 'auth.register')]
    #[Throttle(max: 3, per: 60)]
    public function register(ServerRequestInterface $request): Response
    {
        $body = json_decode((string) $request->getBody(), true) ?? [];

        if (empty($body['email']) || empty($body['password']) || empty($body['name'])) {
            return Response::json(['error' => 'Missing required fields'], 400);
        }

        // Check for duplicate email
        $existing = $this->auth->findByEmail($body['email']);
        if ($existing !== null) {
            return Response::json([
                'error'   => 'Validation failed',
                'details' => ['email' => 'Email already registered'],
            ], 422);
        }

        $result = $this->auth->register($body);

        return Response::json([
            'data' => [
                'message'       => 'Registration successful',
                'user'          => [
                    'id'        => $result['user']->id,
                    'email'     => $result['user']->email,
                    'full_name' => $result['user']->full_name,
                ],
                'access_token'  => $result['access_token'],
                'refresh_token' => $result['refresh_token'],
                'token_type'    => 'Bearer',
                'expires_in'    => $result['expires_in'],
            ],
        ], 201);
    }

    #[Route('GET', '/me', name: 'auth.me')]
    #[Authenticated]
    public function me(ServerRequestInterface $request): Response
    {
        // NOTE: The attribute is 'auth.user', NOT 'user'
        $user = $request->getAttribute('auth.user');

        return Response::json([
            'data' => [
                'id'         => $user->id,
                'email'      => $user->email,
                'full_name'  => $user->full_name,
                'status'     => $user->status,
                'created_at' => $user->created_at->format('c'),
            ],
        ]);
    }
}

Tip: Always use $request->getAttribute('auth.user') — the AuthenticationMiddleware sets the attribute as auth.user, not user.

Frontend: API Client

Create a reusable API client that handles JWT tokens, automatic refresh, and typed requests.

`src/lib/api.ts`

"use client";

const API_URL = process.env.NEXT_PUBLIC_API_URL || "http://localhost:8088";

interface ApiOptions {
  method?: string;
  body?: unknown;
  headers?: Record<string, string>;
  token?: string | null;
}

class ApiClient {
  private baseUrl: string;

  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }

  private getToken(): string | null {
    if (typeof window === "undefined") return null;
    return localStorage.getItem("mm_token");
  }

  async request<T = unknown>(path: string, options: ApiOptions = {}): Promise<T> {
    const { method = "GET", body, headers = {}, token } = options;
    const authToken = token ?? this.getToken();

    const res = await fetch(`${this.baseUrl}${path}`, {
      method,
      headers: {
        "Content-Type": "application/json",
        ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
        ...headers,
      },
      body: body ? JSON.stringify(body) : undefined,
    });

    // Auto-refresh on 401
    if (res.status === 401) {
      const refreshed = await this.refreshToken();
      if (refreshed) {
        return this.request<T>(path, { ...options, token: this.getToken() });
      }
      this.clearTokens();
      throw new Error("Unauthorized");
    }

    if (!res.ok) {
      const err = await res.json().catch(() => ({ error: res.statusText }));
      throw new Error(err.error || err.message || "Request failed");
    }

    return res.json();
  }

  private async refreshToken(): Promise<boolean> {
    const refresh = typeof window !== "undefined"
      ? localStorage.getItem("mm_refresh")
      : null;
    if (!refresh) return false;

    try {
      const res = await fetch(`${this.baseUrl}/api/v2/auth/refresh`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ refresh_token: refresh }),
      });

      if (!res.ok) return false;

      const data = await res.json();
      if (data.data?.access_token) {
        localStorage.setItem("mm_token", data.data.access_token);
        if (data.data.refresh_token) {
          localStorage.setItem("mm_refresh", data.data.refresh_token);
        }
        return true;
      }
      return false;
    } catch {
      return false;
    }
  }

  private clearTokens() {
    if (typeof window !== "undefined") {
      localStorage.removeItem("mm_token");
      localStorage.removeItem("mm_refresh");
      window.location.href = "/login";
    }
  }

  // ── Auth Methods ──────────────────────────────────────────
  login(email: string, password: string) {
    return this.request<{
      data: {
        access_token: string;
        refresh_token: string;
        user: { id: number; email: string; full_name: string };
      };
    }>("/api/v2/auth/login", { method: "POST", body: { email, password } });
  }

  register(name: string, email: string, password: string, companyName: string) {
    return this.request<{
      data: {
        access_token: string;
        refresh_token: string;
        user: { id: number; email: string; full_name: string };
      };
    }>("/api/v2/auth/register", {
      method: "POST",
      body: { name, email, password, company_name: companyName },
    });
  }
}

export const api = new ApiClient(API_URL);

Frontend: Auth Context Provider

Wrap your app with AuthProvider to share auth state across all components.

`src/lib/auth.tsx`

"use client";

import React, {
  createContext, useContext, useEffect, useState, useCallback,
  type ReactNode,
} from "react";
import { api } from "./api";

interface User {
  id: number;
  name: string;
  email: string;
}

interface AuthState {
  user: User | null;
  loading: boolean;
  login: (email: string, password: string) => Promise<void>;
  register: (
    name: string, email: string, password: string, companyName: string
  ) => Promise<void>;
  logout: () => void;
}

const AuthContext = createContext<AuthState | null>(null);

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);

  // On mount: validate stored token by calling /me
  useEffect(() => {
    const token = localStorage.getItem("mm_token");
    if (token) {
      api
        .request<{ data: { id: number; email: string; full_name: string } }>(
          "/api/v2/auth/me"
        )
        .then((res) =>
          setUser({
            id: res.data.id,
            email: res.data.email,
            name: res.data.full_name,
          })
        )
        .catch(() => {
          localStorage.removeItem("mm_token");
          localStorage.removeItem("mm_refresh");
        })
        .finally(() => setLoading(false));
    } else {
      setLoading(false);
    }
  }, []);

  const login = useCallback(async (email: string, password: string) => {
    const res = await api.login(email, password);
    localStorage.setItem("mm_token", res.data.access_token);
    localStorage.setItem("mm_refresh", res.data.refresh_token);
    // Map full_name → name for frontend consistency
    const u = res.data.user;
    setUser({ id: u.id, email: u.email, name: u.full_name });
  }, []);

  const register = useCallback(
    async (
      name: string, email: string, password: string, companyName: string
    ) => {
      const res = await api.register(name, email, password, companyName);
      localStorage.setItem("mm_token", res.data.access_token);
      localStorage.setItem("mm_refresh", res.data.refresh_token);
      const u = res.data.user;
      setUser({ id: u.id, email: u.email, name: u.full_name });
    },
    []
  );

  const logout = useCallback(() => {
    localStorage.removeItem("mm_token");
    localStorage.removeItem("mm_refresh");
    setUser(null);
    window.location.href = "/login";
  }, []);

  return (
    <AuthContext.Provider value={{ user, loading, login, register, logout }}>
      {children}
    </AuthContext.Provider>
  );
}

export function useAuth() {
  const ctx = useContext(AuthContext);
  if (!ctx) throw new Error("useAuth must be used within AuthProvider");
  return ctx;
}

Note: The API returns full_name but we map it to name in the frontend User interface for simplicity. This mapping happens in three places: login, register, and the /me response handler.

Wire Into Layout — `src/app/layout.tsx`

import { AuthProvider } from "@/lib/auth";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider>{children}</AuthProvider>
      </body>
    </html>
  );
}

Frontend: Register Page

`src/app/(auth)/register/page.tsx`

"use client";

import { useState } from "react";
import { useRouter } from "next/navigation";
import Link from "next/link";
import { useAuth } from "@/lib/auth";

export default function RegisterPage() {
  const { register } = useAuth();
  const router = useRouter();
  const [name, setName] = useState("");
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [companyName, setCompanyName] = useState("");
  const [error, setError] = useState("");
  const [loading, setLoading] = useState(false);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setError("");
    setLoading(true);

    try {
      await register(name, email, password, companyName);
      router.push("/login"); // Redirect to login after registration
    } catch (err: unknown) {
      setError(err instanceof Error ? err.message : "Registration failed");
    } finally {
      setLoading(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <h1>Create Account</h1>

      {error && <div className="error">{error}</div>}

      <input type="text"     value={name}        onChange={(e) => setName(e.target.value)}        placeholder="Full name"    required />
      <input type="email"    value={email}       onChange={(e) => setEmail(e.target.value)}       placeholder="Email"        required />
      <input type="password" value={password}    onChange={(e) => setPassword(e.target.value)}    placeholder="Password"     required />
      <input type="text"     value={companyName} onChange={(e) => setCompanyName(e.target.value)} placeholder="Company name" required />

      <button type="submit" disabled={loading}>
        {loading ? "Creating..." : "Create Account"}
      </button>

      <p>Already have an account? <Link href="/login">Sign in</Link></p>
    </form>
  );
}

Frontend: Login Page

`src/app/(auth)/login/page.tsx`

"use client";

import { useState } from "react";
import { useRouter } from "next/navigation";
import Link from "next/link";
import { useAuth } from "@/lib/auth";

export default function LoginPage() {
  const { login } = useAuth();
  const router = useRouter();
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [error, setError] = useState("");
  const [loading, setLoading] = useState(false);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setError("");
    setLoading(true);

    try {
      await login(email, password);
      router.push("/"); // Redirect to dashboard
    } catch (err: unknown) {
      setError(err instanceof Error ? err.message : "Login failed");
    } finally {
      setLoading(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <h1>Welcome Back</h1>

      {error && <div className="error">{error}</div>}

      <input type="email"    value={email}    onChange={(e) => setEmail(e.target.value)}    placeholder="Email"    required />
      <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" required />

      <button type="submit" disabled={loading}>
        {loading ? "Signing in..." : "Sign in"}
      </button>

      <p>Don't have an account? <Link href="/register">Create one</Link></p>
    </form>
  );
}

Frontend: Protected Routes

Wrap dashboard pages with a layout that redirects unauthenticated users.

`src/app/(dashboard)/layout.tsx`

"use client";

import { useEffect } from "react";
import { useRouter } from "next/navigation";
import { useAuth } from "@/lib/auth";

export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  const { user, loading } = useAuth();
  const router = useRouter();

  useEffect(() => {
    if (!loading && !user) {
      router.push("/login");
    }
  }, [user, loading, router]);

  if (loading) {
    return <div>Loading...</div>;
  }

  if (!user) return null;

  return <>{children}</>;
}

Using the User in Components

"use client";

import { useAuth } from "@/lib/auth";

export default function ProfileCard() {
  const { user, logout } = useAuth();

  return (
    <div>
      <h2>Welcome, {user?.name}</h2>
      <p>{user?.email}</p>
      <button onClick={logout}>Sign Out</button>
    </div>
  );
}

Token Refresh Flow

The API client handles token refresh automatically. Here's the sequence:

Browser makes a request (e.g. GET /api/v2/messages)
API Client attaches the stored Bearer token
If the API returns 401 Unauthorized (token expired):
- Client sends POST /api/v2/auth/refresh with the refresh token
- On success: stores the new tokens and retries the original request
- On failure: clears all tokens and redirects to /login

Token Lifetimes

Token	Lifetime	Storage Key
Access Token	30 minutes	`localStorage("mm_token")`
Refresh Token	7 days	`localStorage("mm_refresh")`

Warning: If both tokens are expired (user inactive for 7+ days), the client clears storage and redirects to /login.

Common Issues & Solutions

1. `TypeError: Cannot assign string to property ... of type DateTimeImmutable`

Cause: DatabaseUserProvider in MonkeysLegion ≤ 2.0.7 does raw assignment from PDO strings to typed properties.

Fix: Upgrade to monkeyscloud/monkeyslegion:^2.0.8 which includes castValue() type coercion in the hydrator.

2. `/me` returns `null` user — `$request->getAttribute('user')` is null

Cause: The AuthenticationMiddleware sets the attribute as auth.user, not user.

Fix:

- $user = $request->getAttribute('user');
+ $user = $request->getAttribute('auth.user');

3. `422 Unprocessable Content` on register

Cause: The email is already registered. The API returns:

{ "error": "Validation failed", "details": { "email": "Email already registered" } }

Fix: Use a different email, or parse the error details in the frontend to show a specific message.

4. `full_name` vs `name` mismatch

Cause: The API returns full_name but your frontend User interface expects name.

Fix: Map the field in every place you read user data:

setUser({ id: u.id, email: u.email, name: u.full_name });

5. CORS errors from `localhost:3000` → `localhost:8088`

Cause: The API needs CORS headers for cross-origin requests.

Fix: Add CORS middleware in your MonkeysLegion middleware stack:

// config/middleware.mlc
MonkeysLegion\Http\Middleware\CorsMiddleware::class

Or set the environment variable:

CORS_ORIGINS=http://localhost:3000

6. Page redirects to `/login` on refresh despite being logged in

Cause: The /me endpoint crashes (often the DateTimeImmutable bug), so the auth provider clears tokens and sets user = null.

Fix: Upgrade MonkeysLegion to 2.0.8+ and verify /me works:

curl -s http://localhost:8088/api/v2/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Quick Reference

# Register a user via curl
curl -X POST http://localhost:8088/api/v2/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "securepass123",
    "company_name": "Acme Inc."
  }'

# Login
curl -X POST http://localhost:8088/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "password": "securepass123"}'

# Get current user
curl http://localhost:8088/api/v2/auth/me \
  -H "Authorization: Bearer <access_token>"

# Refresh token
curl -X POST http://localhost:8088/api/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<refresh_token>"}'

MonkeysLegion

MonkeysLegion 2.0 Is Released — Introducing Apex AI and a Faster PHP Runtime

Jorge Peraza — Tue, 28 Apr 2026 22:43:51 +0000

MonkeysLegion 2.0 is officially released.

This is more than a framework update. It is a full architectural step forward for the MonkeysLegion ecosystem: a faster runtime, a cleaner PHP 8.4+ foundation, a stronger modular package structure, and a new AI orchestration layer built directly for modern PHP applications.

PHP has always been one of the most productive languages on the web.

It powers SaaS platforms, APIs, internal tools, content systems, enterprise applications, dashboards, automation workflows, and products used by millions of people every day.

But modern teams are building in a different environment now.

They need faster boot times.

They need clean architecture.

They need APIs by default.

They need cloud-native deployment.

They need observability.

They need DevOps-friendly workflows.

They need AI-ready applications.

They need developer experience without hidden runtime magic.

That is why we are releasing MonkeysLegion 2.0.

MonkeysLegion 2.0 is built for developers and teams who want the clarity of raw PHP, the structure of a serious framework, the productivity of a modular ecosystem, and the performance profile of a runtime that gets out of the way.

Why MonkeysLegion 2.0 Matters

Laravel built an incredible ecosystem.

Forge, Vapor, Nova, Cashier, queues, jobs, billing tools, starter kits, and one of the largest PHP communities in the world. If you need a batteries-included SaaS starter, Laravel is hard to beat.

Symfony powers some of the most mission-critical enterprise systems on earth.

Its profiler, debug toolbar, reusable components, release discipline, and enterprise credibility are best-in-class.

MonkeysLegion is built for a different moment.

A moment where teams want:

Raw throughput
PHP 8.4+ architecture
Attribute-first development
Minimal runtime overhead
Clean dependency injection
Modular packages
API-first structure
DevOps automation
Cloud-native deployment
Observability
AI orchestration
Enterprise-ready foundations

No unnecessary heavy boot process.

No runtime proxies.

No hidden magic.

No fighting the framework.

Just your code, clean architecture, and a framework designed to move fast from local development to production.

What Changed in 2.0

MonkeysLegion 2.0 is a full architectural pass across the framework and package ecosystem.

The release focuses on:

PHP 8.4+ native architecture
Attribute-first routing and configuration
Compiled dependency injection
Typed MLC configuration
PSR-compliant HTTP and middleware layers
Production-ready security middleware
OpenAPI-first API development
A modular package ecosystem
Better developer tooling
Faster runtime behavior
AI orchestration with Apex AI

The goal is simple:

Make PHP feel modern again — fast, clean, modular, typed, observable, deployable, and ready for AI-native applications.

PHP 8.4+ Native Architecture

MonkeysLegion 2.0 is designed around modern PHP instead of legacy conventions.

The framework is moving deeper into:

Strict types
PHP attributes
Property hooks
Constructor injection
Typed configuration
Compiled containers
PSR standards
Clean service boundaries
Lightweight runtime behavior

The main idea is that your application should be readable from the code itself.

Routes should be visible.

Services should be explicit.

Configuration should be understandable.

Controllers should be clean.

Database logic should be predictable.

Deployment should not require guessing.

MonkeysLegion 2.0 keeps the code close to the developer.

Attribute-First Development

MonkeysLegion 2.0 uses PHP attributes as a first-class architecture pattern.

Routes, validation rules, service providers, commands, middleware, and AI tools can be declared close to the code they affect.

Example:

use MonkeysLegion\Http\Attributes\Route;
use Psr\Http\Message\ResponseInterface;

final class ProjectController
{
  #[Route('/api/projects', methods: ['GET'])]
  public function index(): ResponseInterface
  {
    return $this->json($this->projects->list());
  }
}

This makes applications easier to understand.

You open a controller and immediately see:

The endpoint
The HTTP method
The handler
The dependencies
The response flow

For teams building APIs, dashboards, SaaS platforms, internal tools, CMS platforms, or microservices, this matters.

Compiled Dependency Injection

Dependency injection should help developers, not confuse them.

MonkeysLegion 2.0 continues the direction of a clean, predictable container that favors explicit services, typed dependencies, and production compilation.

The goal is not to create a magical container that hides everything.

The goal is to make dependency management simple:

use Psr\Log\LoggerInterface;

final class ProjectService
{
  public function __construct(
    private ProjectRepository $projects,
    private LoggerInterface $logger,
  ) {}
}

Your services are clear.

Your dependencies are explicit.

Your application is easier to test.

Your architecture is easier to reason about.

In production, the framework can compile container definitions so applications avoid unnecessary runtime reflection on the hot path.

That is one of the core performance principles behind MonkeysLegion 2.0.

Performance Is a Core Feature

Performance is not a marketing layer in MonkeysLegion 2.0.

It is part of the architecture.

The framework is designed around zero-magic PHP objects, compiled routing, compiled dependency injection, attribute discovery at cache/build time, and a lean PSR middleware pipeline.

The performance direction is based on several key principles:

Zero-magic architecture

Entities, DTOs, resources, and enums should behave like plain PHP objects.
No proxy-heavy runtime model

The framework avoids forcing every application through runtime proxy layers.
Compiled routing and DI

Discovery happens before production runtime where possible.
Lean middleware pipeline

Middleware should be powerful, but the request path should remain predictable.
PHP 8.4+ features

The framework embraces modern PHP language improvements instead of simulating them with legacy patterns.

On the current MonkeysLegion benchmarks, the framework is positioned around major improvements over heavier runtime approaches:

Entity creation: around 140× faster than Laravel
DTO construction: around 60× faster than Laravel
Enum operations: around 25× faster than Laravel
Resource serialization: around 5.5× faster than Laravel
HTTP throughput: around 12.5K requests/sec vs Laravel’s ~2.1K requests/sec
Cold boot memory: significantly lower than heavier full-stack boot processes

These benchmark numbers should be understood in context: benchmarks depend on hardware, PHP version, configuration, JIT, opcache, test harness, and workload.

But the architectural direction is clear:

MonkeysLegion 2.0 is designed to reduce runtime overhead and make high-performance PHP applications easier to build.

API-First by Default

Modern applications are API-driven.

A backend is rarely just a backend anymore. It may serve:

A web app
A mobile app
A dashboard
A CMS
A CLI
A partner integration
An AI workflow
A microservice
A third-party API consumer

MonkeysLegion 2.0 is designed with APIs as a first-class concern.

The framework and skeleton are moving toward a complete API foundation with support for:

PSR-7 and PSR-15 HTTP handling
Middleware pipelines
JWT authentication
RBAC
API keys
Validation
DTO binding
OpenAPI documentation
Swagger UI
Rate limiting
Security headers
Request IDs
CORS
Trusted proxies

That means teams can build real production APIs without stitching together half a dozen disconnected tools.

Introducing Apex AI

The biggest new direction in the MonkeysLegion ecosystem is Apex AI.

Apex AI is an AI orchestration package for PHP 8.4+.

It is not just another OpenAI wrapper.

Apex AI is designed to bring production-ready AI infrastructure into PHP with a clean, framework-native developer experience.

The goal is simple:

Build AI-powered applications in PHP without stitching together multiple disconnected tools.

Apex AI introduces a unified way to work with multiple AI providers, route requests intelligently, build pipelines, manage cost, use tools, stream responses, and create real AI workflows inside PHP applications.

What Apex AI Brings to PHP

Apex AI is designed around the needs of real production applications.

It focuses on:

Unified AI provider interface
Multi-provider routing
OpenAI support
Anthropic support
Google AI Studio support
Vertex AI support
Ollama/local model support
Smart model routing
Fallback chains
Declarative AI pipelines
Guardrails
Structured outputs
Tool calling with PHP attributes
Streaming with Server-Sent Events
Agent-style workflows
Multi-agent crews
Memory strategies
Cost tracking
Budget controls
Model Context Protocol support
Clean integration with MonkeysLegion applications

This matters because AI development is moving beyond simple prompt calls.

Modern AI applications need:

Routing
Retries
Fallbacks
Guardrails
Tool execution
Structured responses
Memory
Context management
Cost controls
Streaming
Evaluation
Observability

Apex AI brings these ideas into PHP as part of the MonkeysLegion ecosystem.

AI-Native PHP Applications

PHP developers should not need to leave PHP to build serious AI workflows.

Many companies already have PHP backends, PHP teams, PHP infrastructure, PHP CMS platforms, PHP APIs, and PHP business logic.

The question is not whether PHP can be used for AI applications.

The question is whether the ecosystem gives PHP developers the right tools.

Apex AI is built around that belief.

With Apex AI, a PHP application can become:

An AI-powered CMS
An AI-assisted dashboard
A document processing system
A content generation platform
A support automation tool
An internal agent workflow
A SaaS product with AI features
A developer platform with AI orchestration
A backend that routes between cloud and local models

This is where MonkeysLegion 2.0 becomes more than a framework release.

It becomes the foundation for AI-native PHP development.

Example: Tool Calling with Attributes

Apex AI is designed to feel natural inside modern PHP.

Instead of forcing AI workflows into disconnected configuration files, tools can be represented as PHP code.

Example:

use MonkeysLegion\Apex\Attributes\Tool;

final class ProjectTools
{
  #[Tool(
    name: 'find_project',
    description: 'Find a project by ID and return its current status.'
  )]
  public function findProject(string $id): array
  {
    return $this->projects->findStatus($id);
  }
}

This keeps AI tools close to the domain logic of the application.

The result is easier to read, easier to test, and easier to maintain.

Built for SaaS, Internal Tools, and Enterprise Platforms

MonkeysLegion 2.0 is not only for small apps.

It is being designed for companies building:

SaaS platforms
Internal business tools
Developer portals
Admin dashboards
API platforms
Automation systems
AI-enabled products
Cloud-native services
CMS-driven websites
Enterprise applications

Many companies do not need another heavy framework that assumes one way of working.

They need a framework that lets them move fast while keeping the codebase clean.

MonkeysLegion gives teams a structured foundation without forcing unnecessary complexity.

Apex AI extends that foundation into AI-powered product development.

Modular Ecosystem

One of the most important ideas behind MonkeysLegion is modularity.

You should not need to install a giant framework if you only need one part of it.

MonkeysLegion is moving toward a package ecosystem where teams can use the pieces they need:

Core
Router
Dependency Injection
HTTP
Security
Database
Query Builder
Migration
Authentication
Validation
Internationalization
Telemetry
DevTools
CLI
GraphQL
Apex AI
Cloud tooling
Testing utilities
CMS-related packages

This package-first approach makes the framework flexible.

Small projects can stay small.

Large projects can grow with structure.

Enterprise teams can standardize around the packages that matter to them.

Telemetry and Observability

Modern applications need visibility.

It is not enough for a framework to run code. Teams need to understand what is happening in production.

MonkeysLegion 2.0 treats observability as part of the developer platform, not as an afterthought.

That includes visibility into:

Request performance
Application health
Security events
API usage
Background processes
AI requests
Model routing
Provider fallbacks
Cost tracking
Latency
Error rates

This becomes even more important with Apex AI.

AI applications need observability because model behavior, token usage, latency, provider availability, and costs all affect production reliability.

Cloud-Native From the Start

MonkeysLegion is not being designed only for local development.

It is being built with deployment in mind.

Modern teams need applications that can move from local development to containers, servers, CI/CD pipelines, and cloud environments without massive rewrites.

That matters because software delivery is no longer just about writing PHP classes.

It is about the full lifecycle:

Build
Test
Package
Deploy
Monitor
Scale
Improve

MonkeysLegion 2.0 is being shaped around that complete workflow.

A Better Developer Experience Without Heavy Runtime Cost

Developer experience matters.

But developer experience should not require hiding everything behind magic.

MonkeysLegion 2.0 is focused on a balanced philosophy:

Give developers speed, structure, and useful defaults — without making the runtime heavy or the code difficult to understand.

That means:

Clear file structure
Fast boot process
Explicit dependencies
Attribute-based configuration
Useful CLI commands
Strong defaults
Modular packages
Production-ready skeleton
Easy local setup
Cloud-ready conventions
AI-ready workflows

The framework should feel productive without becoming opaque.

Inspired by the Best, Built With a Different Philosophy

MonkeysLegion is not trying to replace Laravel or Symfony.

They are excellent frameworks with massive ecosystems and proven track records.

But not every team wants the same tradeoffs.

Laravel is great when you want a large ecosystem and rapid application scaffolding.

Symfony is great when you want enterprise components, stability, and deep configurability.

MonkeysLegion is for teams that want:

A lighter framework
Less magic
More direct control
Modern PHP-first architecture
Fast APIs
Modular packages
Cloud-native defaults
Strong developer tooling
Clean enterprise structure
AI orchestration built into the ecosystem

It is not about copying the old model.

It is about building a framework for where PHP is going next.

Built as an Ecosystem, Not Just a Framework

MonkeysLegion 2.0 is part of a bigger vision.

The framework is the foundation, but the ecosystem is the real goal.

That ecosystem includes:

MonkeysLegion Framework
MonkeysLegion Skeleton
MonkeysLegion DevTools
MonkeysLegion GraphQL
MonkeysLegion Telemetry
MonkeysLegion Apex AI
MonkeysCMS
Cloud deployment tooling
AI-ready developer workflows
Enterprise package roadmap

This matters because modern teams do not only need a router or container.

They need a complete development platform.

MonkeysLegion is moving toward that full-stack ecosystem while keeping the core lightweight and modular.

MonkeysCMS and the Future of AI-Ready Content Platforms

MonkeysLegion also powers the direction behind MonkeysCMS.

MonkeysCMS is being designed as a modern, code-first CMS built on top of the MonkeysLegion framework.

This is one of the strongest examples of why MonkeysLegion matters.

A framework is not only valuable when it can serve a JSON response.

It becomes powerful when it can support real products:

CMS platforms
Admin systems
API products
AI workflows
Enterprise dashboards
Developer platforms

With Apex AI, the CMS direction becomes even stronger.

Content systems are one of the clearest places where AI can help:

Generate drafts
Improve content
Critique content
Translate content
Classify content
Extract metadata
Build summaries
Power editorial assistants
Automate workflow tasks

MonkeysLegion 2.0 is the foundation for that future.

Open Source and Community-Driven

MonkeysLegion is open source.

The project started from a simple belief:

Modern PHP projects deserve a framework that is fast, cloud-native, AI-ready, and clear to work with.

Version 2.0 is a call to developers, agencies, founders, and engineering teams:

Come test it.

Break it.

Improve it.

Build with it.

Open issues.

Submit pull requests.

Share ideas.

Help shape the next generation of PHP tooling.

Who MonkeysLegion 2.0 Is For

MonkeysLegion 2.0 is for developers and teams who want to build serious software with PHP.

It is for the solo founder building a SaaS product.

It is for the agency building multiple client platforms.

It is for the backend engineer building APIs.

It is for the enterprise team that needs maintainable internal tools.

It is for the startup that wants speed without technical debt.

It is for the developer who loves PHP but wants a framework that feels modern, clean, fast, and ready for AI-powered products.

It is for builders who want control.

Getting Started

The easiest way to start is with the official skeleton.

composer create-project monkeyscloud/monkeyslegion-skeleton my-app
cd my-app
composer serve

From there, you can begin building APIs, services, dashboards, internal tools, SaaS applications, AI workflows, CMS platforms, or custom products using the MonkeysLegion architecture.

Useful links:

Website: monkeyslegion.com
Release article: monkeyslegion.com/news/2026-04/monkeyslegion-2-announcing
Framework: github.com/MonkeysCloud/MonkeysLegion
Skeleton: github.com/MonkeysCloud/MonkeysLegion-Skeleton

Final Thoughts

MonkeysLegion 2.0 is built with a clear belief:

PHP is not done.

PHP is still one of the most important languages on the web. But the ecosystem needs new ideas, new tooling, and new frameworks that match how software is built today.

MonkeysLegion is our answer.

A feather-light framework.

A modular ecosystem.

A cloud-native foundation.

A clean architecture for modern PHP.

A faster runtime path.

A developer platform built for speed, clarity, and scale.

An AI orchestration layer for the next generation of PHP applications.

Version 2.0 is not the finish line.

It is the foundation.

Welcome to MonkeysLegion 2.0.

Welcome to Apex AI.

Let’s build the next era of PHP.

I Replaced GitHub + Jira + Vercel + PlanetScale + Datadog With One Free Platform

Jorge Peraza — Mon, 06 Apr 2026 15:07:29 +0000

Every month I was paying for five tools that didn't talk to each other.

GitHub for code ($20/mo for the team). Jira for tasks ($8/user/mo). Vercel for some deploys ($20/user/mo). A database host ($40/mo). Datadog for monitoring ($75/mo). Plus the Slack tax of context-switching between all of them 50 times a day.

Total: ~$400/month. Five logins. Five billing dashboards. Five permission systems. Zero integration between them.

When someone on my team merged a PR, I had to:

Check GitHub to see the diff
Switch to Jira to update the ticket
Switch to Vercel to see if the deploy succeeded
Switch to Datadog to check if metrics look healthy
Go back to Jira to move the ticket to Done

That's five context switches for one merge. Multiply by 10 merges a day. That's 50 tab switches. Research says each context switch costs 20-30 minutes of deep focus. We were bleeding productivity.

So I Built One Platform

I'm a developer. The answer was obvious: build one tool that does all of it.

MonkeysCloud is what I built. It's a single platform with:

Git hosting — repos, PRs, branches, merge queues, branch protection
Task management — Kanban boards, Scrum sprints, time tracking, labels
Hosting — 32 stacks, auto-detect, auto-build, auto-deploy
Databases — MySQL, PostgreSQL, Redis, MongoDB
AI — code review on every PR, build failure analysis, deploy risk scoring
Documentation — wiki, knowledge base, API docs
Monitoring — metrics, logs, uptime checks, alerts

And here's the part that matters: it's free.

What "Free" Actually Means

Not a 14-day trial. Not "free until you hit 100 builds." Actually free:

What you get	Free tier
Compute instances per project	2 free
Database instances per project	2 free
Team members	Unlimited
Projects	Unlimited
Git repositories	Unlimited
Custom domains + SSL	Yes
AI code review	Yes
Kanban boards + sprints	Yes
Monitoring + logs	Yes
Documentation wiki	Yes

The Part That Changed My Workflow

The killer feature isn't any single thing — it's the integration.

When a developer creates a branch named feature/PROJ-42-auth, the platform automatically links that branch, every commit on it, the PR, the build, the preview environment, and the deploy back to task PROJ-42.

The task timeline shows:

Task created by Sarah
Branch feature/PROJ-42-auth created
4 commits pushed
PR #17 opened
AI review: 2 suggestions (resolved)
Build #84 passed
PR merged to main
Deploy #91 to production ✓
Task auto-moved to Done

Nobody manually updated the task. Nobody copy-pasted a Jira ticket number. Nobody checked three tabs to verify the deploy. It just happened.

My project manager sees the full lifecycle of every feature without asking anyone for a status update. The board moves itself.

The AI Actually Helps

I've been burned by "AI-powered" tools that are just ChatGPT wrappers. MonkeysAI is different because it has context — it accesses the actual codebase, task board, build logs, deploy history, and monitoring data.

When a build fails, it doesn't say "check your configuration." It says:

Build failed: TypeScript type mismatch on line 42 of Auth.tsx. The function handleLogin expects string but receives string | undefined. Introduced in commit abc123. Fix: add a null check or update the type signature.

When I'm about to deploy to production, it gives a risk score:

Deploy risk: MEDIUM. Changes 3 files in the payment module. Test coverage for changed code: 62% (below project average of 78%). Recommendation: verify checkout flow in preview before promoting.

These are not generic suggestions. They reference my actual files, my actual test coverage, my actual deploy history.

32 Stacks — Zero Config

I push code. MonkeysCloud reads composer.json, package.json, go.mod, requirements.txt, Gemfile, Cargo.toml, or whatever — and generates the entire build config automatically.

Stacks I've deployed without writing a single line of configuration:

PHP: Laravel, Symfony, WordPress, Drupal, my own MonkeysLegion framework
JavaScript: Next.js, Nuxt, Remix, SvelteKit, Astro, Express, NestJS, React, Vue, Angular
Python: Django, FastAPI, Flask, Streamlit
Ruby: Rails
Go: any Go project (compiles to binary, 30-second deploys)
Rust: Actix, Axum, Rocket
Java: Spring Boot
.NET: ASP.NET Core
Elixir: Phoenix
Custom: Dockerfile, Docker Compose

You can override everything, but for 90% of projects, you push code and it just works.

What It Costs (For Real)

Solo developer, side project: $0/month. Two free servers + two free databases. Custom domain. AI code review. Task board.

Going to production: $19/month. One always-on Starter instance. Keep your free instances for dev and staging.

Startup, 5 devs, 2 projects: ~$177/month. Team plan ($59) + Pro production ($79) + Plus database ($39). Everything else free. Compare to $400+ across five separate tools.

Agency, 12 clients: ~$135/month. Most clients on free instances. A few on Starter ($19 each). Team plan ($59). All client stakeholders invited free.

Try It

Push your code and get a live URL in 60 seconds: monkeys.cloud

I built this because I was tired of context-switching between five tools that cost $400/month combined. Now my entire workflow — code, tasks, deploys, databases, AI, docs, monitoring — lives in one place.

If you've felt the same frustration, give it 5 minutes. The worst that happens is you deploy a project for free.

I'm Jorge, the founder of MonkeysCloud. I'm building this in public and shipping fast. Follow along or roast my work — either way, I'd love to hear what you think in the comments.

We're Giving Away Free Servers With Every Project — App, Database, Cache, Worker. No Trial. No Credit Card.

Jorge Peraza — Sun, 05 Apr 2026 21:16:28 +0000

Today we're launching something that no other developer platform offers: every project you create on MonkeysCloud gets free compute instances and free database instances. Not a 30-day trial. Not $5 in credits. Real servers that run your code and your database — for as long as you need them.

Here's what that means in practice.

What You Get — Per Project, No Strings

Every project on MonkeysCloud includes:

Instance	What it runs	Size	Cost
Free server 1	Your application (any of 32 stacks)	1 GB RAM	$0
Free server 2	A worker, second service, or another app	1 GB RAM	$0
Free database 1	MySQL 8.4, PostgreSQL 16, or MongoDB 7	1 GB RAM	$0
Free database 2	Redis 7 cache, or a second database	1 GB RAM	$0

That's 4 free instances per project. Each one can run any role — app server, database, cache, queue worker, scheduler, or a custom Docker container. You choose.

No credit card required. No time limit. No usage cap. You sign up, create a project, select your stack, push code, and you have a running application with a database and a cache at a live URL.

What Exactly Runs on These Free Instances?

Let me make this concrete. Here's what you can deploy right now for $0:

A complete Laravel stack:

Instance 1: Laravel app (FrankenPHP, PHP 8.4)
Instance 2: Queue worker (processing jobs)
Database 1: MySQL 8.4 (your primary database)
Database 2: Redis 7 (sessions + cache)

Total cost: $0. That's a production-capable Laravel application with a relational database, a cache layer, and background job processing.

A Next.js full-stack app:

Instance 1: Next.js (Node 22, SSR)
Database 1: PostgreSQL 16
Database 2: Redis 7

Total cost: $0. Three instances. Full-stack JavaScript with a real database.

A Django + Celery setup:

Instance 1: Django (Gunicorn)
Instance 2: Celery worker
Database 1: PostgreSQL 16
Database 2: Redis 7 (Celery broker)

Total cost: $0. Background tasks, a real database, and a message broker.

A microservices project:

Instance 1: Go API
Instance 2: Node.js service
Database 1: PostgreSQL 16
Database 2: MongoDB 7

Total cost: $0. Two services and two different database engines.

Every project. Any stack. App + database + cache + worker. Free.

The Fine Print (There's Not Much)

Sleep after 30 minutes. Free instances sleep after 30 minutes with no incoming traffic. When the next request arrives, the instance wakes in 3 to 5 seconds. Your data on disk — database files, uploaded files, application state — is preserved while sleeping. This is fine for development, staging, demos, internal tools, client previews, and sites with intermittent traffic.

Custom domains and SSL work. Every instance — including free ones — supports custom domains with auto-provisioned SSL via Let's Encrypt. You can point myapp.com at a free instance and it works.

Two sizes of free. There are actually two free sizes:

Size	CPU	RAM	SSD	Cost
Free	Shared 0.25 vCPU	1 GB	1 GB	$0
Starter	Shared 0.5 vCPU	2 GB	10 GB	$0

Both are free. Both sleep after 30 minutes. Both count toward your free instance quota. Pick whichever fits your workload.

2 + 2 is the starting point. A free account gets 2 compute instances + 2 database instances per project. But that quota grows as you add paid instances (more on that below).

The Platform Is Free Too

The free instances are just the infrastructure. The platform that wraps them is also free:

Git hosting. Unlimited private repositories with Smart HTTP and SSH access. Or mirror from GitHub, GitLab, or Bitbucket.

Pull requests. Create PRs, leave inline reviews, run merge queues, enforce branch protection. Three merge strategies: merge commit, squash, rebase.

AI code review. Every PR gets an automated review in seconds — security vulnerabilities, performance issues, bugs, and best practices. Inline comments with suggested fixes. Before your team even opens the PR.

Task management. Kanban boards and Scrum sprints. Tasks auto-link to branches, PRs, builds, and deploys through branch naming. The board updates itself — nobody manually moves tickets to "Done."

Monitoring. Response times, error rates, CPU, memory, bandwidth — real-time dashboards with zero setup. Structured log viewer with search and live streaming.

Documentation. Built-in Markdown wiki with version history, search, and collaborative editing. API docs, runbooks, onboarding guides — next to your code and tasks.

Unlimited team members. Invite your entire team — developers, designers, product managers, clients, contractors. Everyone gets full access. No per-seat pricing. No "viewer" seats. Free.

How It Scales: The Tier System

Here's the part I'm most proud of. When you add a paid instance (Plus at $39/mo or above) to any project, your entire organization gets upgraded:

Paid Instances in Org	Org Tier	Max Projects	Free Instances per Project
0	Free	2	2 + 2
1	Starter	5	3 + 3
2–3	Growth	10	4 + 4
4–7	Pro	20	5 + 5
8–15	Business	50	6 + 6
16–30	Scale	100	7 + 7
31+	Enterprise	Unlimited	7 + 7

One paid instance upgrades every project. Add a single Plus ($39/mo) to Project A, and Projects B, C, D, and E all get 3 free compute + 3 free database instances each. The paid instance benefits your entire org, not just the project it lives in.

And here's the kicker: Plus, Pro, and Business include a 90-day free trial. You add a Plus instance, pay $0 for 90 days, and immediately get Starter tier benefits across your entire organization. Five projects. Three free instances each. Before paying a single dollar.

32 Stacks — You Pick, We Build

When you create a project, you select your stack from 32 options. MonkeysCloud generates the complete build configuration — base image, install commands, build steps, start command — based on your selection. Push code. We handle the rest.

PHP: Laravel, Symfony, WordPress, Drupal, MonkeysLegion, PHP Generic
JavaScript/TypeScript: Next.js, Nuxt, Remix, SvelteKit, Astro, Express, NestJS, React SPA, Vue SPA, Angular
Python: Django, FastAPI, Flask, Streamlit, Python Generic
Ruby: Rails, Ruby Generic
Go
Rust
Java: Spring Boot, Java Generic
.NET
Elixir: Phoenix
Other: Static Site, Docker, Docker Compose

You pick the stack. We configure the build pipeline. You push code. It deploys.

What It Costs When You Need More

The free tier handles development, staging, demos, and low-traffic production. When you need always-on instances with more compute for real production traffic:

Size	RAM	SSD	Price	Always-On
Free	1 GB	1 GB	$0	No (sleeps)
Starter	2 GB	10 GB	$0	No (sleeps)
Plus	4 GB	25 GB	$39/mo (90 days free)	Yes
Pro	8 GB	60 GB	$79/mo (90 days free)	Yes
Business	16 GB	120 GB	$149/mo (90 days free)	Yes
Scale	32 GB	250 GB	$299/mo	Yes
Power	64 GB	500 GB	$599/mo	Yes
HC-32 → HC-64	128–256 GB	1–2 TB	$1,199–$2,399/mo	Yes

The jump from free to paid is Plus at $39/month — with 90 days free. That gives you 4 GB RAM, 25 GB SSD, always-on, and immediately upgrades your org tier so every project gets more free instances.

Who This Is For

Solo developers. Deploy your side project, portfolio, or MVP with a database. Free. Custom domain. SSL. AI code review. Push to deploy.

Startups. Run your development and staging environments on free instances. Add a Pro ($79, 90 days free) for production. Your 5-person team uses the platform for free — Git, tasks, deploys, monitoring, docs. Compare to $400/month across GitHub + Jira + Vercel + database host + Datadog.

Agencies. Create a project per client. Most client sites run on free instances with a custom domain. Larger clients upgrade to Plus or Pro for always-on. Invite client stakeholders to their project board for free. Fifteen developers, twelve clients — all free.

Open-source projects. Host your project, track issues, deploy documentation sites, and give contributors AI-reviewed PRs. Free. Apply for our Open Source Partner program for additional instance credits and a free Team plan.

Students and educators. Learn real-world dev workflows — Git, pull requests, CI/CD, databases, monitoring — on a platform that doesn't expire after 30 days. Apply for our Education Partner program for free Team plans and instance credits.

Try It Right Now

No pitch. No "schedule a demo." No "talk to sales."

Go to monkeys.cloud
Sign up (GitHub or Google, 10 seconds)
Create a project, select your stack
Push your code
You have a live URL with a database

The worst that happens is you deploy a project for free and decide it's not for you.

The best that happens is you replace five tools with one and never context-switch again.

→ monkeys.cloud

FAQ for the Skeptics

"How do you make money if the servers are free?"

The free instances are small (1–2 GB) and sleep when idle. They cost us very little to run on shared infrastructure. When your project needs always-on production hosting with dedicated compute and more resources, you add paid instances starting at $39/month with 65–79% gross margins. The free tier is the acquisition funnel. The paid tier is the business.

"What's the catch?"

Free instances sleep after 30 minutes. That means a 3–5 second wake time on the first request after sleeping. For production sites where every millisecond matters, you upgrade to a paid always-on instance. For everything else — dev, staging, demos, internal tools, side projects, client previews — the sleep/wake cycle is fine.

"Will the free tier disappear?"

We reserve the right to modify free tier limits with 30 days' notice (see our Terms). We have no plans to remove the free tier — it's our primary acquisition channel and the core of our growth model. But we're honest: we don't use the phrase "free forever" because we can't predict the future. What we can say is that the free tier is fundamental to how MonkeysCloud works, and removing it would require fundamentally changing the business.

"How is this different from Railway/Render/Heroku?"

Railway gives you a 30-day trial with $5 credit — then you pay per minute. Render's free tier sleeps after 15 minutes with 750 hours/month. Heroku eliminated free dynos entirely. None of them include Git hosting, task management, AI code review, documentation, or monitoring. MonkeysCloud gives you all of that — plus 4 free instances per project — in one integrated platform.

"How is this different from Vercel/Netlify?"

Vercel and Netlify are frontend-first. They deploy React, Next.js, and static sites. They don't host PHP, Python, Go, Ruby, Java, or Rust backends. They don't run MySQL, PostgreSQL, or Redis. They don't have task management or AI code review. MonkeysCloud is full-stack — 32 frameworks, real databases, real backend hosting.

"Can I actually run a production site on the free tier?"

If your site gets intermittent traffic and a 3–5 second wake time is acceptable, yes. Many blogs, portfolios, documentation sites, internal tools, and low-traffic client sites run fine on free instances with a custom domain and SSL. For high-traffic production with instant response, upgrade to Plus ($39/mo, 90 days free).

I'm Jorge, the founder of MonkeysCloud. I built this because I was tired of paying $400/month for five tools that didn't talk to each other. Now I'm giving away free servers to every developer who wants to ship faster. Questions, feedback, or roasts — drop them in the comments. I read every one.

Stop Bidding Against 200 People for $5 Projects — There's a Better Way

Jorge Peraza — Tue, 10 Mar 2026 03:08:13 +0000

If you've spent any time on traditional freelance platforms, you know the drill.

You find a project that fits your skills perfectly. You spend 30 minutes crafting a thoughtful proposal. You hit submit — and immediately see you're proposal #47 out of 50 slots. Half of them are undercutting you by 80%. The client ghosts everyone and reposts the job two weeks later.

It's exhausting. And it doesn't have to be this way.

Introducing MonkeysWorks — An AI-Powered Freelance Marketplace Built for Developers

MonkeysWorks is a new kind of freelance platform launching soon, and we're opening the doors early for freelancers who want to get in before the crowd.

👉 Join the Prelaunch Waitlist as a Freelancer

What Makes MonkeysWorks Different?

🤖 AI Does the Heavy Lifting

MonkeysWorks uses AI at every step of the process — not as a gimmick, but to genuinely save you time and surface the right opportunities.

Smart job matching that learns your skills, stack, and preferences
AI-assisted proposals so you spend time doing the work, not selling it
Automated project scoping to help clients define what they actually need before they post

No more sifting through 300 irrelevant listings looking for the one real opportunity.

💻 Built by Developers, for Developers

MonkeysWorks isn't a generic gig marketplace. It's designed for technical freelancers — developers, DevOps engineers, architects, and technical writers — who build real things and deserve to be compensated accordingly.

The platform supports the full modern stack and understands the difference between "build me a website" and "I need a Next.js frontend with SSR, integrated with a headless CMS and deployed on GCP."

💰 Transparent, Fair Pricing

No race to the bottom. MonkeysWorks is designed to reward quality and expertise, not whoever submits the cheapest bid in the first 10 minutes.

Clients on the platform are vetted and come ready to pay fair rates for serious work.

🚀 Get In Early — Early Freelancers Win

Platforms reward early adopters. Getting in before launch means:

Higher visibility when clients start posting
Priority access to the first wave of projects
Influence over platform features — we genuinely listen to early members
Founding member status with perks we're still cooking up

Who Should Join?

MonkeysWorks is a great fit if you are:

A full-stack or backend developer (PHP, Node, Python, Go, you name it)
A frontend developer working with React, Vue, or Next.js
A DevOps / cloud engineer comfortable with GCP, AWS, or containerized workloads
A technical freelancer tired of platforms that treat you like a commodity

If you're serious about your craft and want to work with clients who respect that — this is for you.

How to Join

It takes less than a minute.

→ Sign up at monkeysworks.com/join/freelancers

Leave your info, tell us a bit about your stack, and we'll reach out before the public launch with early access details.

The Bottom Line

The freelance market isn't broken because there isn't enough work. It's broken because the platforms that connect freelancers to clients were built to maximize transaction volume — not freelancer success.

MonkeysWorks is being built differently. AI-first, developer-focused, and designed so that the best person for the job actually gets it.

Come build with us.

Join the MonkeysWorks Prelaunch →

Have questions or want to share feedback? Drop a comment below — the team reads everything.

MonkeysAI — Live Playground (Development Preview)

Jorge Peraza — Fri, 13 Feb 2026 04:24:10 +0000

We just launched something we've been building quietly inside the Monkeys ecosystem:

👉 MonkeysAI — Live Playground

This isn't a wrapper around a third-party API.

There are:

No OpenAI tokens
No external proxy layer
No hidden API dependency

It runs on our own infrastructure.

What Is MonkeysAI?

MonkeysAI is the AI layer for MonkeysCMS and MonkeysLegion — designed to integrate AI directly into content workflows at the architecture level.

Not as a plugin. Not as a SaaS add-on. As core infrastructure.

The Live Playground exposes the API directly in the browser so developers can test behavior before integrating it.

What You Can Do in the Playground

🧠 Generate
Create new content from a short brief.

✨ Improve
Enhance clarity, tone, structure, or formatting of existing content.

🔎 Critique & Refine
Analyze content and automatically improve weak sections.

Smart Model Routing

One of the key pieces we built is dynamic model selection.

Instead of forcing users to choose a model manually, we route intelligently:

⚡ Fast Mode → Optimized for speed and lightweight generation
🧠 Reasoning Mode → Used for deeper analysis and structured logic
🎯 Auto Mode → Automatically selects the best model for the task

This allows:

Lower cost per request
Faster response times when complexity isn't required
Heavy reasoning only when necessary

Why Build It This Way?

Most AI integrations today:

Proxy requests to external APIs
Add latency
Lock you into vendor pricing
Break when token limits change

We wanted:

Infrastructure control
Predictable performance
Cost transparency
Full integration into CMS-level workflows

This approach required:

Custom orchestration
Model routing logic
Dedicated servers
Continuous dataset crawling & validation

It's slower to build — but architecturally cleaner.

Development Preview Notice

This is an early public preview.

We are actively improving:

Response quality
Crawling verification accuracy
Performance optimization
Output stability under load

It's not polished. But it's real.

What's Next?

The Playground is just step one.

The goal is deeper AI-native CMS features like:

Inline multilingual optimization (25+ languages)
Structured content reasoning
SEO-aware generation
AI-assisted migrations
Editorial workflow automation

Try It

If you're building:

A CMS
An AI product
A content engine
Or your own LLM infrastructure

I'd genuinely love feedback.

Try it. Stress it. Break it. Tell me what to improve.

👉 monkeyscms.com/#ai-playground

— Jorge

MonkeysLegion GraphQL 2.0 — A Complete Rewrite, Built for the Future

Jorge Peraza — Wed, 11 Feb 2026 22:30:05 +0000

When I started working on MonkeysLegion GraphQL, the goal was simple:
Make GraphQL feel native to modern PHP.

Version 2.0 is not an upgrade.
It's a complete architectural rewrite.

👉 Repo: MonkeysLegion-GraphQL

Why a Complete Rewrite?

GraphQL in PHP often feels:

Too coupled to webonyx
Configuration-heavy
Reflection-expensive
Hard to secure properly
Difficult to scale for real production workloads

So instead of patching the old system… I rebuilt it from scratch.

What's New in 2.0

🧩 Attribute-Driven Schema Definition

No more schema arrays. No more manual wiring.
Everything is powered by PHP 8.4 attributes.

#[Type]
class UserType
{
    #[Field]
    public function id(): int {}

    #[Field]
    public function name(): string {}
}

#[Query]
class UserQuery
{
    #[Field]
    public function user(#[Arg] int $id): User {}
}

Supported attributes:

#[Type] · #[Field] · #[Query] · #[Mutation] · #[Subscription] · #[Arg] · #[InputType] · #[Enum] · #[InterfaceType] · #[UnionType] · #[Middleware]

Clean. Typed. Explicit.

⚙️ New Architecture (Builder Pipeline)

The entire schema generation system is now modular:

SchemaBuilder
TypeBuilder
FieldBuilder
InputTypeBuilder
EnumBuilder
ArgumentBuilder

No magic factory classes. No static schema definitions. Just a clean build pipeline.

🧠 GraphQLContext (Immutable Execution Context)

Every request now gets an immutable execution context — HTTP request, authenticated user, DI container, and DataLoaderRegistry:

$context = new GraphQLContext(
    request: $request,
    user: $user,
    container: $container
);

Predictable. Safe. Testable.

🚀 Performance: DataLoader + Batch Execution

DataLoader — per-request caching + batching. No more N+1 query nightmares.

abstract class DataLoader {
    abstract protected function batchLoad(array $keys): array;
}

Per-request caching
Batch loading
Registry-based resolution

BatchExecutor — supports multiple operations in one request. Useful for complex clients, microfrontend architectures, and optimized API gateways.

🔒 Security Built-In

Security is not optional anymore. MonkeysLegion GraphQL 2.0 includes:

DepthLimiter
ComplexityAnalyzer
IntrospectionControl
PersistedQueries
RateLimiter

Production-ready from day one.

🧱 Custom Scalars Included

Out of the box support for: DateTime · JSON · Email · URL · Upload

No need to reimplement common scalars.

🔄 Subscriptions (Modern Protocol)

WebSocket layer completely rewritten.

❌ Removed subscriptions-transport-ws
✅ Now using graphql-ws

New components:

SubscriptionServer
SubscriptionManager
PubSubInterface
InMemoryPubSub / RedisPubSub
WsAuthenticator

Removed heavy dependencies like Ratchet/React. Cleaner. Faster. Modern.

🗂 Schema Caching (PSR-16)

Reflection is expensive. So we cache it.

SchemaCache
SchemaCacheWarmer

CLI commands:

php mlc graphql:cache:warm
php mlc graphql:cache:clear

Zero-runtime schema rebuilds in production.

🧾 Input Validation System

Built-in validation layer with InputValidator and RuleSet. Structured validation errors via ValidationError and AuthorizationError.

No need to plug external validation unless you want to.

🔌 PSR-15 Middleware Support

Fully PSR-15 compatible:

GraphQLMiddleware
GraphiQLMiddleware
UploadMiddleware

Drop into any modern PHP stack.

🧬 Entity Integration

Native support for mapping domain entities via EntityTypeMapper and EntityResolver.

Makes MonkeysLegion's entity system work seamlessly with GraphQL.

🔗 Relay Pagination Support

ConnectionType · EdgeType · PageInfoType

Ready for modern frontend clients.

🧰 CLI Tooling

Built-in CLI commands:

graphql:schema:dump
graphql:schema:validate
graphql:cache:warm
graphql:cache:clear
graphql:introspect

GraphQL now feels like a first-class framework citizen.

⚠️ Breaking Changes

This is version 2.0 for a reason.

Changed:

What	Before → After
Minimum PHP version	→ 8.4
WebSocket protocol	→ graphql-ws
Configuration	→ .mlc files (typed)
Types	No longer extend webonyx base classes

Removed:

Schema\SchemaFactory
Support\Scanner
Execution\Executor
WebSocket\WsHandler
Ratchet/React dependencies

Everything replaced with cleaner architecture.

Why This Matters

This release is about performance, security, modern PHP design, clean architecture, and production-readiness.

It's not just "GraphQL working in PHP."
It's GraphQL designed for serious applications.

What's Next?

Federation support
Advanced query cost modeling
Observability hooks
Native OpenTelemetry integration
Extended subscription drivers

Final Thoughts

MonkeysLegion GraphQL 2.0 is the foundation for everything I'm building next — AI-native CMS (MonkeysCMS), scalable SaaS APIs, real-time systems, and high-performance microservices.

Rewriting it was painful. But worth it.

If you're building serious PHP applications and want modern GraphQL done right:

👉 MonkeysLegion-GraphQL on GitHub

MonkeysLegion: Ship Production-Ready PHP in Minutes, Not Days 🚀

Jorge Peraza — Wed, 28 Jan 2026 23:51:09 +0000

TL;DR: MonkeysLegion is a lightweight, modular PHP framework that bundles everything you need—blazing-fast router, DI container, CLI tools, and zero-config Docker—so you can focus on features instead of plumbing. It's MIT-licensed, open-source, and we're looking for collaborators!

Why Another PHP Framework?

Let's be honest: setting up a new PHP project can feel like assembling IKEA furniture without instructions. You need routing, dependency injection, database migrations, authentication, validation, caching... and by the time you've wired it all together, you've lost the motivation to build the actual thing.

MonkeysLegion changes that.

We built it because we were tired of the boilerplate. We wanted something that's:

⚡ Fast to start — One composer command, and you're coding
🧩 Modular — Use only what you need
🔒 Production-ready — Built-in auth, validation, caching, and observability
📖 Well-documented — Because code without docs is just legacy waiting to happen

Get Started in 60 Seconds

composer create-project monkeyscloud/monkeyslegion-skeleton my-app
cd my-app
cp .env.example .env
php ml key:generate
composer serve

Open http://127.0.0.1:8000 — you're live. 🎉

What's in the Box?

MonkeysLegion isn't just another micro-framework. It's a complete ecosystem:

Category	What You Get
HTTP Stack	PSR-7/15 compliant, middleware pipeline
Routing	Attribute-based, auto-discovery, caching
Database	Query Builder, Micro-ORM, Migrations
Auth	JWT, RBAC, 2FA, OAuth, API Keys
Validation	DTO binding with attribute constraints
Caching	File, Redis, Memcached drivers
CLI	Migrations, scaffolding, Tinker REPL
Telemetry	Prometheus metrics, distributed tracing

Code That Speaks for Itself

Attribute-Based Routing

No more giant route files. Define routes right where they belong:

use MonkeysLegion\Router\Attributes\Route;
use MonkeysLegion\Router\Attributes\RoutePrefix;
use MonkeysLegion\Router\Attributes\Middleware;

#[RoutePrefix('/api/users')]
#[Middleware(['cors', 'throttle'])]
class UserController
{
    #[Route('GET', '/', name: 'users.index')]
    public function index(): Response
    {
        return $this->json(User::all());
    }

    #[Route('GET', '/{id:\d+}', name: 'users.show')]
    public function show(string $id): Response
    {
        return $this->json(User::find($id));
    }

    #[Route('POST', '/', name: 'users.create')]
    #[Middleware('auth')]
    public function create(CreateUserRequest $request): Response
    {
        // Validated DTO is automatically injected
        $user = User::create($request->validated());
        return $this->json($user, 201);
    }
}

Validation with DTOs

Type-safe request validation using PHP attributes:

use MonkeysLegion\Validation\Attributes as Assert;

final readonly class CreateUserRequest
{
    public function __construct(
        #[Assert\NotBlank]
        #[Assert\Email]
        public string $email,

        #[Assert\NotBlank]
        #[Assert\Length(min: 8, max: 64)]
        public string $password,

        #[Assert\Url]
        public ?string $website = null,
    ) {}
}

Invalid requests automatically return structured errors:

{
  "errors": [
    { "field": "email", "message": "Value must be a valid e-mail." },
    { "field": "password", "message": "Minimum length is 8 characters." }
  ]
}

Fluent Query Builder

Write readable database queries without raw SQL:

$users = $qb->from('users')
    ->leftJoin('profiles', 'p', 'p.user_id', '=', 'users.id')
    ->select(['users.*', 'p.avatar'])
    ->where('status', '=', 'active')
    ->whereIn('role', ['admin', 'editor'])
    ->orderBy('created_at', 'DESC')
    ->paginate(page: 1, perPage: 20);

Built-in Authentication

JWT auth with 2FA support, ready to use:

$result = $auth->login($email, $password, $request->ip());

if ($result->requires2FA) {
    return response()->json([
        'requires_2fa' => true,
        'challenge' => $result->challengeToken,
    ]);
}

return response()->json([
    'access_token' => $result->tokens->accessToken,
    'refresh_token' => $result->tokens->refreshToken,
]);

Powerful CLI Tools

Scaffold your app without leaving the terminal:

php ml make:entity User          # Generate Entity
php ml make:controller User      # Generate Controller
php ml make:migration            # Generate migration from entity diff
php ml migrate                   # Run migrations
php ml tinker                    # Interactive REPL
php ml openapi:export            # Export OpenAPI spec

The Package Ecosystem

MonkeysLegion is built as independent packages. Use the full stack or pick what you need:

monkeyslegion-core — Kernel, events, helpers
monkeyslegion-router — Full-featured routing
monkeyslegion-auth — JWT, RBAC, 2FA, OAuth
monkeyslegion-query — Query Builder & ORM
monkeyslegion-cache — PSR-16 multi-driver cache
monkeyslegion-files — File storage, chunked uploads, S3
monkeyslegion-mail — SMTP, templates, DKIM, queues
monkeyslegion-i18n — Internationalization
monkeyslegion-telemetry — Metrics & tracing
monkeyslegion-validation — DTO validation
monkeyslegion-template — MLView templating engine

Requirements

PHP 8.4+
MySQL 8.4 (recommended)
Composer 2.x

We Need You! 🤝

MonkeysLegion is open-source and MIT-licensed. We're actively looking for collaborators who want to:

🐛 Report bugs and suggest features
📝 Improve documentation
🧪 Write tests
💡 Build new packages
🌍 Help with translations

No contribution is too small. Whether it's fixing a typo or implementing a new feature, we'd love to have you on board.

Join Our Community

We've set up a Slack workspace where you can:

Ask questions and get help
Discuss features and architecture
Share what you're building
Connect with other developers

👉 Join MonkeysLegion on Slack

Resources

🌐 Website: monkeyslegion.com
📚 Documentation: monkeyslegion.com/docs
💻 GitHub: MonkeysCloud/MonkeysLegion-Skeleton
📦 Packagist: monkeyscloud/monkeyslegion-skeleton

Get Started Now

composer create-project monkeyscloud/monkeyslegion-skeleton my-app

Give it a ⭐ on GitHub if you like what you see!

Built with 💚 by developers who believe PHP deserves better tooling.

What do you think? Have you tried MonkeysLegion? What features would you like to see? Drop a comment below or join us on Slack! 👇

🧠 MonkeysCMS: An AI-Native CMS Built on MonkeysLegion — Rethinking Content Platforms from the Core

Jorge Peraza — Wed, 07 Jan 2026 02:12:47 +0000

Most CMS platforms are built on top of frameworks they don't control.

That single fact explains why:

Extensibility feels bolted-on
Performance tuning is painful
AI integration feels awkward
Developer experience degrades over time

MonkeysCMS exists because we chose a different path.

Instead of adapting a CMS to a framework,
we built a framework specifically to power a modern, AI-native CMS.

That framework is MonkeysLegion.

👉 CMS repo: https://github.com/MonkeysCloud/MonkeysCMS

👉 Framework ecosystem: https://github.com/MonkeysCloud

🚨 Why Existing CMS Architectures Hit a Ceiling

Modern content systems must handle:

Headless & hybrid rendering
API-first delivery
Multi-channel publishing
Automation-heavy workflows
AI-assisted content creation
Long-term maintainability

Yet most CMS platforms fall into one of these traps:

❌ Legacy CMS (Drupal, WordPress, etc.)

Powerful but heavy
Tight coupling everywhere
AI added as plugins
Framework constraints leak into CMS logic

❌ Modern SaaS Headless CMS

Closed source
Usage-based pricing explosions
Limited extensibility
No control over core behavior

The missing piece?

A CMS built on a framework designed explicitly for content systems and automation.

🐒 Enter MonkeysLegion: The Foundation

MonkeysLegion is a modern, modular backend framework built with one goal:

Give developers full control over architecture without sacrificing productivity.

It is:

Lightweight
Explicit
Modular
Framework-agnostic
Built for APIs, automation, and extensibility

MonkeysCMS is not using MonkeysLegion accidentally —
it is a direct expression of its design philosophy.

🏗️ Why Build a CMS on Its Own Framework?

Because CMSs are not just CRUD apps.

They need:

Strong domain modeling
Pluggable logic layers
Predictable extension points
Performance control
AI integration at the core

MonkeysLegion provides:

🧱 Modular packages (Router, Auth, Cache, Query, CLI, etc.)
🔌 Clean dependency boundaries
🧠 Explicit data flow (no magic globals)
🧪 Testable components by default

This lets MonkeysCMS stay:

Clean
Maintainable
Extensible without hacks

🧩 Architecture Overview: CMS + Framework + AI

Think of the system like this:

┌─────────────┐
│   Frontend  │  (Next.js, Astro, Svelte, Apps)
└─────▲───────┘
      │ API
┌─────┴───────┐
│  MonkeysCMS │  Content, Schemas, Workflows
└─────▲───────┘
      │ Core Services
┌─────┴───────┐
│ MonkeysLegion│  Routing, Auth, Storage, CLI
└─────▲───────┘
      │ Intelligence
┌─────┴───────┐
│  MonkeysAI  │  AI workflows & automation
└─────────────┘

Each layer has one responsibility — and nothing leaks.

🧠 MonkeysAI: AI Where It Actually Belongs

Because MonkeysCMS is built on MonkeysLegion, AI isn't a hack.

MonkeysAI integrates cleanly into:

Content pipelines
Workflow automation
Schema interpretation
Semantic enrichment

This enables:

Context-aware content suggestions
AI-assisted editing (not replacement)
Automated content operations
Future schema-aware generation

AI becomes a system capability, not a plugin checkbox.

🛠️ Developer Experience Is a First-Class Feature

MonkeysLegion enforces discipline that benefits MonkeysCMS developers:

No hidden container magic
No global state abuse
Clear service contracts
Predictable lifecycle

As a contributor, this means:

You can understand modules in isolation
You don't need to learn "CMS magic"
Your changes don't break unrelated systems

If you've ever said:

"I hate fighting the framework just to add a feature"

This stack was built for you.

📦 Modular by Nature (Not by Marketing)

Because MonkeysCMS inherits MonkeysLegion's modularity:

Every CMS feature is a module
AI capabilities are pluggable
APIs are versionable
Integrations are isolated

This makes:

Custom deployments easy
Enterprise use viable
Long-term maintenance realistic

No forks. No hacks. No rewrites.

🌍 Real-World Use Cases

This architecture is ideal for:

AI-driven content platforms
SaaS documentation hubs
Multi-brand editorial systems
Investor/startup platforms
Knowledge bases & research portals
CMS + automation hybrids

Anywhere content needs to be structured, automated, and intelligent.

🧑‍💻 Contributing: CMS, Framework, or AI

You don't need to contribute to everything.

You can help with:

MonkeysCMS features
MonkeysLegion core packages
MonkeysAI workflows
Documentation
DX improvements
Integration examples

This is an ecosystem — not a monolith.

👉 Start here: https://github.com/MonkeysCloud/MonkeysCMS

🛣️ What's Ahead

Roadmap highlights:

Visual schema builders
AI-powered content ops
Plugin marketplace
Advanced workflow automation
Multi-tenant support
Performance-focused deployments

All driven by MonkeysLegion's stability and AI-native design.

🧠 Final Thought

MonkeysCMS is not "just another CMS".